Skip to main content

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.

python deps model calls License

中文


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.2

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"]}
  • review means a human decides. It is not "look again later".
  • pass requires a rule that says pass. A document no rule matched is review (NO_RULE_MATCHED) — nothing falls through to a silent allow.
  • A missing field or a wrongly-typed field never becomes pass. Missing fields are review; 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 fail and both are reported.
  • A pass reason is never reported beside a stricter one. When rules with different verdicts match the same document, the pass entries are dropped and only the fail / review entries remain: "no departure found" beside "here is the departure" is a contradiction, not information. The engine does this, so a pack does not have to express "no other rule fired" in every pass rule. This changed in 0.1.1 — 0.1.0 reported both — and it is the one change in that release that can alter the reasons array of an existing pack. Verdicts and exit codes are unaffected: a pass entry is only ever dropped when the verdict was already going to be fail or review.
  • model_calls is a real counter, and it is always 0.

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 subset_of matches exists missing.

in / not_in take a scalar on the left and test membership in the list on the right. subset_of takes an array on the left and asks whether every element of it appears in the list on the right — the only way to express "all of these declared keys are in the allowed vocabulary":

# the field's array must be a subset of the allowed list; note the `not:`
- id: r_allergens_mappable
  when:
    not:
      field: allergens_declared
      op: subset_of
      value: [celery, eggs, fish, milk, mustard, nuts, peanuts, sesame_seeds, soybeans]
  then: {verdict: review, reason_code: ALLERGEN_KEY_NOT_MAPPABLE, cite: [c1]}
  require_fields: [allergens_declared]

An empty array is a subset of every list, so "nothing declared" never reads as "something outside the vocabulary". Elements are compared kind-for-kind, the same way every other operator in this language compares values: true, 1 and "1" are three different things, so [1] is not a subset of [true]. Passing an array to in / not_in is a TYPE_ERROR (the verdict becomes review) and the message says to use subset_of.

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.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for phocinae-rulepack 0.1.2
File Size Uploaded Provenance Actions
phocinae_rulepack-0.1.2.tar.gz 66.1 kB Without provenance Details for phocinae_rulepack-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for phocinae-rulepack 0.1.2
File Interpreter ABI Platform Actions
phocinae_rulepack-0.1.2-py3-none-any.whl Python 3 none any Details for phocinae_rulepack-0.1.2-py3-none-any.whl

Total release size: 123.2 kB

Release files / phocinae_rulepack-0.1.2.tar.gz

Download URL phocinae_rulepack-0.1.2.tar.gz
Size 66.1 kB
Tags Source
SHA-256 checksum
How to use checksums
c58d2b472c228505f1c993d53d7bd3b91e9ca7986c4435cfc3398bf9cedaf0cd
BLAKE2b-256 checksum
How to use checksums
d8eb5798bf8bd24edbb7cdc714187ca944e779e90fef0fb355d1af4f74322e8e
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.2-py3-none-any.whl

Download URL phocinae_rulepack-0.1.2-py3-none-any.whl
Size 57.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bebb1a69367b74e7fc95393124561b183f72ed799fe891bd6618eb65571ebb8c
BLAKE2b-256 checksum
How to use checksums
f9068f5ac1f9345ef53661221f98f907e2401dc6c2411f07445d117201ffe04e
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.2

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page