Metadata-Version: 2.4
Name: knitweb-knitfield
Version: 0.1.0
Summary: Pure PoUW decision algorithm — the fabric of knit decisions; zero dependencies, embeddable everywhere
Author-email: Edwin Hauwert <develuse@gmail.com>
License: MIT
Project-URL: Repository, https://github.com/Knitweb/knitfield
Project-URL: Issues, https://github.com/Knitweb/knitfield/issues
Keywords: knitweb,proof-of-work,settlement,knitfield,decision-algorithm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"

# knitfield — The Fabric of Decision

The pure, dependency-free reasoning engine behind Knitweb's Proof-of-Useful-Work settlement.
Where individual decision threads (knits) are woven together into the proof fabric.

## Design

**knitfield** answers one fundamental question: given a claimed proof of work, does it satisfy the
job's verification policy and therefore warrant settlement?

```
Job Class Registry  →  (e.g., "synaptic-compile", "distill", "smart-contract-procedure")
                ↓
        Verification Policy  →  (e.g., "uniform" = deterministic; "split" = structural + challenge window)
                ↓
    Pure Decision Predicate  →  (e.g., split_settles: deterministic_ok AND window_closed AND NOT dispute_upheld)
                ↓
        Settlement Decision  →  (accept work, mint token reward, or slash)
```

Knitfield is embedded *locally* in every Knitweb node, running inside the node's process alongside
its Fabric memory state. There is no central server — each peer independently applies knitfield's
logic to weave decisions into the proof fabric, accepting or rejecting work proofs through the P2P
network.

## Architecture

```
src/knitweb_knitfield/
  __init__.py
  registry.py       — JobClass, register_job_class, job_class, verification_policy
  settlement.py     — split_settles (pure predicate for distill/split-verified work)
```

## Zero Dependencies

Knitfield imports only Python stdlib. It carries no crypto, networking, or data-structure
dependencies, so it can run in any context (IoT, embedded, pure Python, JVM via Jython, etc.) —
the decision logic is universally portable.

## Usage

```python
from knitweb_knitfield import register_job_class, VERIFICATION_UNIFORM, split_settles

# Register a new job type
register_job_class("my-custom-job", VERIFICATION_UNIFORM)

# Query the registry
policy = job_class("my-custom-job").verification
assert policy == VERIFICATION_UNIFORM

# Pure settlement decision for split-verified work (distill, etc.)
is_settlement_ok = split_settles(
    deterministic_ok=True,
    window_closed=True,
    dispute_upheld=False,
)
assert is_settlement_ok is True
```

## Integration with Knitweb

- **Heart** (`Knitweb/heart`): depends on knitfield; exports the registry + settlement policy.
- **Vein** (`Knitweb/vein`): depends on knitfield; registers the "smart-contract-procedure" job class.
- **Molgang** (`Knitweb/molgang`): uses knitfield to decide work settlement in the P2P quorum.
- **Ledgerfield** (`Knitweb/ledgerfield`): embeds knitfield in settlement nodes for DAO treasury decisions.

## Docs

See `docs/SETTLEMENT_POLICIES.md` for a detailed explanation of `VERIFICATION_UNIFORM` vs
`VERIFICATION_SPLIT` and how to compose new policies.
