phocinae-publish-gate
Pre-publication checks for media deliverables. It measures facts about a
target and hands them to the phocinae-rulepack
engine, which decides. It never writes to the target, and it never reaches a
verdict on its own.
$ phocinae-publish-gate check episode.mp3 --facts episode.facts.json --pack expense-policy
target : episode.mp3 (declaration)
engine : phocinae-rulepack 0.1.2
counts : pass=0 fail=0 review=3 skip=0
REVIEW r1_no_receipt_over_500 missing:receipt_attached
REVIEW r6_prior_approval_missing missing:prior_approval
REVIEW r7_category_not_in_policy matched:r7_category_not_in_policy
status : REVIEW exit 2 (REVIEW)
What this is, and the one unusual thing about it
This is the first package in its family with a run-time dependency, and the
dependency is the point rather than an accident. The verdict engine lives in
phocinae-rulepack: rule loading, expression evaluation, the three-state output
and the exit-code contract all come from there. Implementing them again here would
mean two engines whose disagreements nobody could adjudicate.
So the split is:
| this project | the kernel |
|---|---|
| measures — runs tools, reads manifests and sidecars | loads rule packs |
| records how each value was obtained | evaluates expressions |
writes a phocinae-facts/v1 document |
returns pass / review / fail |
| aggregates and reports | defines the exit-code numbers |
Because that boundary is a real dependency rather than a convention, the bridge checks its shape instead of assuming it:
$ python -c "import phocinae_publish_gate" # works with the kernel absent
$ phocinae-publish-gate check ... # refuses to run without it
ERROR E_RULEPACK_UNAVAILABLE: the phocinae-rulepack kernel is required and could
not be imported; install it with `pip install phocinae-rulepack`
A version pin answers "is this a release I have seen before". It does not answer
"does this release still expose the names and semantics I call", and those are
different questions: a patch release can rename a public name without that being a
breaking change by semver as commonly practised, and a checkout or a fork can
report any version at all. The failure without a shape check is not a clean error —
it is an AttributeError raised inside a rule evaluation, or, much worse, a run
that completes and reports verdicts computed against different semantics.
So the bridge verifies every name it calls, checks that the kernel's exit-code
numbers still match the ones this project mirrors, and refuses to run if they
do not (E_RULEPACK_API_MISMATCH). It also refuses a kernel whose major version is
outside the supported range even when the shape matches — a matching shape at an
unsupported major usually means the shape is about to change, not that it is safe.
Exit codes
The numbers are the kernel's own, so a caller who already reads one reads the other the same way.
| code | meaning |
|---|---|
0 |
everything passed, with no skips and no reviews |
1 |
at least one fail |
2 |
no failures, but at least one review or skip |
3 |
usage or configuration error, an empty scan, or an internal invariant broken |
The guard that matters
--exit-policy content relaxes exactly one thing: a skip no longer lifts the code
to 2. It does not let "nothing was verified" become success.
A run in which every check skipped has pass=0, fail=0, review=0. A naive reading
of the policy gives exit 0, recording a check that did nothing as a success — the
precise failure this project exists to catch in other people's tooling. So:
counts.pass + counts.fail + counts.review == 0→ always exit 3,E_EMPTY_SCAN, under both policies.
SKIP is not PASS is enforced in the aggregation as well: a skip keeps its own
status in the report — a reader must be able to see what did not run — but it
cannot yield a clean verdict.
Type errors are not findings
A fact of the wrong type is a defect in the measurement, not a property of the
target. If a duration arrives as the string "3.5" instead of the number 3.5,
reporting that as a rule failure would blame the podcast for a bug in the
measurer. So facts are type-checked before the kernel is called, and a type error
is exit 3 (E_FACTS_TYPE_ERROR) rather than a verdict.
Two consequences worth stating:
Trueis not a duration. Booleans are rejected where a number is expected even thoughboolis a subclass ofintin Python.Nonemeans not obtained, which is legitimate, and is recorded asprovenance: unavailablerather than as zero.0.0from a measurement that could not run and0.0from a file that really is silent are the same number and different facts; collapsing them is the thing this project exists to catch.
A field with no recorded provenance defaults to unavailable, never to measured.
Defaulting the other way would make the document claim more than the measurer knows.
Commands
phocinae-publish-gate gates # gates, packs, reason codes
phocinae-publish-gate inspect <pack> # a pack's rules and citations
phocinae-publish-gate check <target> [options] # the main command
phocinae-publish-gate explain <target> --check <id>
phocinae-publish-gate probe | verify-tripwire | capture-fixtures
check takes --facts <path> to evaluate an existing phocinae-facts/v1
document instead of measuring. That is not only a test seam: it is how a caller
checks a target whose measurement happens elsewhere — a CI job that already ran
ffprobe, for instance — without this tool spawning anything.
--out together with --dry-run is refused with E_OUT_REQUIRES_NO_DRY_RUN.
Writing a report is a filesystem write, and dry-run means no writes; the two flags
are in genuine conflict, and silently preferring one would be the wrong kind of
helpful. --dry-run is the default.
There is deliberately no --fix, --apply, --write-tags or --normalize.
No mode of this tool modifies the target.
Scope of this release
The commands that need a measurement backend are not implemented, and they say
so. probe, verify-tripwire and capture-fixtures exit 3 with a message
naming what is missing, rather than being absent from the command surface or
silently doing nothing. A subcommand that quietly no-ops is worse than one that
says it is missing.
check therefore reports skip for measurement (SKIP_NO_MEASUREMENT_BACKEND)
unless you pass --facts. With no pack selected it skips for that reason too
(SKIP_NO_PACK_SELECTED) — and a run of nothing but skips exits 3, by the guard
above.
What is complete and tested: the kernel bridge and its shape check, the closed reason-code set, the exit-code semantics and the empty-scan guard, the fact document and its type discipline, the aggregation, and the CLI contract.
The design specifies four gate packs (q7 manuscript, q8 podcast, q9 music,
c6 declaration) with a total of 78 rules, and the measurement backends that feed
them. Neither is in this release. Shipping a small number of unverified rules would
be worse than shipping none: a rule whose basis nobody checked is decoration, and
this family's whole discipline is that a gate whose citation cannot be resolved is
not a gate.
Environment
Python >=3.10. One run-time dependency, phocinae-rulepack>=0.1.2,<0.2. No
network access at run time.
Testing
python tests/test_publish_gate.py
139 assertions across 11 groups. The ones that matter most are about the
integration, because that is the only place a mistake would be silent: a missing
kernel must be an actionable error rather than an ImportError; a kernel whose API
shape changed must be refused rather than used; and an exit code must never be 0
when nothing was verified.
Several assertions run against the real installed kernel rather than a stub, and
report SKIP if it is absent — and a skip is not a pass.
License
Apache-2.0.
Metadata
Release files for phocinae-publish-gate 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_publish_gate-0.1.1.tar.gz | 38.7 kB | With provenance | Details for phocinae_publish_gate-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| phocinae_publish_gate-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for phocinae_publish_gate-0.1.1-py3-none-any.whl |
Total release size: 70.4 kB
Release files / phocinae_publish_gate-0.1.1.tar.gz
| Download URL | phocinae_publish_gate-0.1.1.tar.gz |
|---|---|
| Size | 38.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b6f7ffd060061f252355408f73df0b31529ceaa5f84bcb74aed0fceca79e25be
|
|
BLAKE2b-256 checksum How to use checksums |
e3259921760b66bb88b8949d03483b8f49ae2c695ba1136ce0b36d9262216346
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency logRelease files / phocinae_publish_gate-0.1.1-py3-none-any.whl
| Download URL | phocinae_publish_gate-0.1.1-py3-none-any.whl |
|---|---|
| Size | 31.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
31d39ac340afcd525878dc83b65ff96651cec39a48c1bb74dea5388b4aa8f946
|
|
BLAKE2b-256 checksum How to use checksums |
7140bbff4360dd06f87f16af25c6ca5ac3e212129f3d24529c2d2449493fd61e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency logSecurity for phocinae-publish-gate 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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for phocinae_publish_gate-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency logA 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.