phocinae-rulepack
Read a ledger, apply one version of a rule pack, and emit only the differences for a human to review. Zero model calls. Zero third-party runtime dependencies.
Why this exists, in one measurement
The same decision model, asked the same question two ways, scored like this on 53 labelled commands:
| how the question was asked | recall on destructive commands |
|---|---|
| "Should this be blocked?" (boolean) | 0.00 — it passed all 31 |
| allow / ask / deny (three-way) | 0.74 |
| harmless / risky / destructive (scale) | 0.97 |
And on a policy-check battery of 14 claims, the rule kernel scored 14/14 with zero model calls, while the same model, asked to approve or reject the claims directly, rejected all 8 compliant ones.
The conclusion this package is built on: "the rule kernel is worth shipping as a deterministic plugin that uses no model at all." This is that kernel.
If you want the measurement harness rather than the kernel, see
phocinae-formulate.
Install
pip install phocinae-rulepack==0.1.1
Python 3.9 or newer. No dependencies. Nothing in this package opens a socket.
Use
# validate a pack: schema, citation text, corpus hashes
phocinae-rulepack validate expense-policy
# run one document (JSON or YAML; '-' reads stdin)
phocinae-rulepack check expense-policy claim.json
# run a ledger and get one envelope
phocinae-rulepack check expense-policy ledger.json --format json
# what ships in the box
phocinae-rulepack list --packs-dir ./packs
Exit codes are the contract:
| code | meaning |
|---|---|
0 |
every result is pass |
1 |
at least one fail |
2 |
no fail, but at least one review (grey zone → a human decides) |
3 |
usage or configuration error, or an empty scan |
Priority is fixed and total: 3 > 1 > 2 > 0.
The three-state result
{"rulepack":"expense-policy","verdict":"fail","model_calls":0,
"reasons":[{"rule":"r2_meal_cap","verdict":"fail","reason_code":"OVER_CATEGORY_CAP",
"cite":["c2","c4"],"evidence":"matched:r2_meal_cap"}],
"unmatched_paths":["id"]}
reviewmeans a human decides. It is not "look again later".passrequires a rule that says pass. A document no rule matched isreview(NO_RULE_MATCHED) — nothing falls through to a silent allow.- A missing field or a wrongly-typed field never becomes
pass. Missing fields arereview; they are never treated as compliance. - A real violation outranks a missing field. If one rule finds a breach and
another cannot be evaluated, the verdict is
failand both are reported. model_callsis a real counter, and it is always0.
The evidence model is the point
A rule is only as good as the text behind it, so a citation must say where its text came from and whether anyone has actually read the instrument:
evidence_level |
meaning | can it fail something? |
|---|---|---|
verbatim |
the quote appears character-for-character in the corpus | yes |
derived |
an authority's restatement, not the instrument's own words | yes, with a warning |
unavailable |
the instrument text was not obtained | no — the verdict is capped to review |
That cap is the difference between an honest tool and a fake gate. A rule whose
basis nobody has read must not be able to reject a customer's paperwork. The cap
is verified in both directions by the test suite: flip the citation to derived
and the same input must move from review to fail.
validate resolves every quote against the corpus and recomputes every
sha256. A one-character change to a quote, or a wrong hash, fails validation.
--strict additionally rejects sample corpus and unavailable citations.
Writing a pack
schema: phocinae-rulepack/v1
id: my-check
title: What this checks
version: 0.1.0
missing_field_policy: review # only 'review' is accepted in v1
corpus:
- path: sources/spec.txt
role: authority # authority | production | sample
sha256: <64 uppercase hex>
citations:
- id: c1
source: Where the text is from
locator: clause 4.2
quote: "the exact words, character for character"
document: sources/spec.txt
evidence_level: verbatim
rules:
- id: r1_limit
when:
all_of:
- {field: amount, op: ">", value: 500}
- {field: receipt, op: "==", value: false}
then: {verdict: fail, reason_code: OVER_LIMIT, cite: [c1]}
require_fields: [amount, receipt]
The expression language is deliberately small: field OP value combined with
all_of / any_of / not, and a value may be {"ref": "other.field"} to
compare two fields. Operators: == != < <= > >= in not_in matches exists missing.
There is no arithmetic, no custom function, no loop, and no network access. If you need a computed value, compute it in the adapter that builds the input document — that keeps the judgement criterion in the pack, where it can be cited and tested.
The two YAML traps worth knowing
Both of these parse into something plausible and wrong, which is why the loader raises instead of guessing:
op: > # WRONG: a folded block scalar. It swallows the lines below.
op: ">" # right: quote operators
note: text with a ": " colon inside # WRONG: YAML wants a new key there
note: "text with a \": \" colon inside" # right: quote it, or use a block scalar
What ships
| pack | scenario | rules | citations | evidence level |
|---|---|---|---|---|
expense-policy |
S15 (the expense pre-approval demo) | 8 | 5 | all verbatim |
eu-label |
XC7 (food label compliance, Ireland) | 8 | 6 | all derived |
filing-requirements |
L10 (court filing requirements, civil first instance) | 13 | 15 | all derived |
Naming note: "S15" here is the gallery's S15 expense demo. In the 182-scenario inventory S15 is something else (multilingual low-resource expansion).
Where each pack's text comes from
expense-policy quotes the policy constants and the rule function of the
measurement script that produced the S15 battery, byte for byte. Everything is
verbatim.
eu-label quotes the Food Safety Authority of Ireland's published guidance on
Regulation (EU) No. 1169/2011. The FSAI advises on the Regulation; these are the
authority's words, not the instrument's own text, so every citation is derived
and validate says so on each run. GAPS.md in the pack directory lists the
rules the design draft carried but this release does not, and what would close
each one.
Two corrections were made to the design draft's citations after fetching the live
pages: the draft's allergen-list entry reads 11. ***Sesame seeds*** and products
thereof while the page reads 11. Sesame seeds and products thereof; and the
draft attributes the small-package x-height of 0.9 mm to the FSAI's FAQ page,
which actually states 0.9 cm. The 0.9 mm figure is taken from the FSAI's
General Labelling page, which matches Annex IV to the Regulation. Both figures and
the disagreement are recorded in sources/fsai_legibility.md rather than smoothed
over.
filing-requirements quotes 法释〔2015〕8号 (最高人民法院关于人民法院登记立案
若干问题的规定) as republished on a court website. A re-publication rather than the
legislature's own database, so every citation is derived. Its citations were
checked against the fetched text and the design draft's quotes all matched.
Scope note for filing-requirements: a missing item escalates to review, never
to fail. Article 7 makes the remedy a one-time written notice to supplement, so
"something is missing" is not the same fact as "something is wrong". Only the copy
count — which Article 6(4) requires to match the number of defendants — can fail,
because there the recorded value itself is non-compliant.
Testing
python tests/run_all.py
No network, no model, no third-party packages. The suite exits non-zero when zero assertions ran — "a check with nothing to check must not report success" is the same rule the engine applies to an empty scan.
Tests never use tempfile: scratch goes to $PHOCINAE_RULEPACK_TMP, or to a
directory beside the repository.
What this is not
It is not a compliance, legal, medical or financial conclusion. It reports differences for a human to review. It is not a model, and it does not call one.
License
Apache-2.0.
Metadata
Release files for phocinae-rulepack 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| phocinae_rulepack-0.1.1.tar.gz | 62.3 kB | Without provenance | Details for phocinae_rulepack-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| phocinae_rulepack-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for phocinae_rulepack-0.1.1-py3-none-any.whl |
Total release size: 116.7 kB
Release files / phocinae_rulepack-0.1.1.tar.gz
| Download URL | phocinae_rulepack-0.1.1.tar.gz |
|---|---|
| Size | 62.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9439f6d0cdb90c031020c87ea3a2a4ea381a16b8d00846ebe4e03951d9a775c2
|
|
BLAKE2b-256 checksum How to use checksums |
9367701843c4a6fa0ac6d27563970090c671941d9e946e4bcf32de440fe090c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / phocinae_rulepack-0.1.1-py3-none-any.whl
| Download URL | phocinae_rulepack-0.1.1-py3-none-any.whl |
|---|---|
| Size | 54.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1a11262a9d806fcd2a2e01983749a88bcd90467d8280be11122dc46546f02523
|
|
BLAKE2b-256 checksum How to use checksums |
4ba5a64638c0294b5731a93deb6cd8c48c6ffbca2db4efe8de9071d45605837d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Security for phocinae-rulepack 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.