florecon 0.2.2

Incremental financial reconciliation by min-cost flow: a conserving combinator algebra over a network-simplex core. Nothing created, nothing lost.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# florecon (Python host)

A generic [wasmtime](https://github.com/bytecodealliance/wasmtime-py) host that
drives self-describing **florecon** reconciliation plugins. The host knows
nothing about any domain: it loads a plugin `.wasm`, reads its `describe()`, and
ships the raw columns the plugin declares. The same code runs every florecon
plugin.

Money is integer minor units; nothing is created or lost.

## Authoring a plugin

This package also ships the `florecon` CLI, so you can build a plugin without
cloning the florecon repo:

```bash
florecon new my-recon       # scaffold a Rust plugin (needs a Rust toolchain)
cd my-recon
florecon author             # fast native loop on data/sample.csv
florecon ship               # build the production solver.wasm
```

Then load `target/wasm32-unknown-unknown/release/solver.wasm` with the host
below. See the scaffolded `README.md` for the full journey.

## Running a plugin

```python
from florecon import Workspace

ws = Workspace("interco_plugin.wasm")     # any florecon plugin wasm

ws.upsert(
    {"row_id": 1, "company": "A", "icp": "B", "objsub": "61500",
     "indicative_usd_amt": 100.0, "trx_currency": "USD", "trx_amt": 100.0,
     "gl_date": 0, "reference": "INV0001"},
    {"row_id": 2, "company": "B", "icp": "A", "objsub": "61500",
     "indicative_usd_amt": -100.0, "trx_currency": "USD", "trx_amt": 100.0,
     "gl_date": 1, "reference": "INV0001"},
)
rep = ws.solve()              # the proposal: groups + per-row allocations
ws.pin_clean(tol=0)           # sign off every clean net-zero match
ws.solve()                    # warm re-solve; pinned groups kept verbatim
```

## Surface

A group lives on a lifecycle axis — `proposed` (the solver's current opinion,
recomputed each `solve`) or `pinned` (your decision, kept verbatim).

```text
ledger      upsert(*rows) · remove(*ids)
machine     solve()
lifecycle   pin(gid) · pin_clean(tol) · pin_singletons(ids) · unpin(gid)
partition   merge(allocs, label, reason) · detach(gid, ids) · dissolve(gid)
read        report()
```

Failures raise `PluginError` carrying a stable `code` (e.g. `"frozen_group"`,
`"conservation_violated"`) plus the `id` / `group_id` it concerns.
`strict_assignments` / `connected_components` project the allocation hypergraph
into per-row assignments or settlement clusters.

The plugin/host ABI is versioned: the host refuses a wasm whose `abi_version`
differs from `florecon.ABI_VERSION`.