v4cat — Symmetry-break cataloguing framework
Grade: quick-start (one-page survey). Deeper: tutorial.md (worked walk-through), then methodology.md (operational design), then theory.md (foundations). Architectural detail: cotype/.
A Python ISA + SQLite schema + MCP server for accumulating named
structural distinctions about a domain. The structural core is
three RISC primitives — introduce_node, edge, kquery —
plus a small declarative-artifact set (breaks, specs, tensions);
every other verb in the ISA is documented sugar that reduces to
these three. The strengthened self-hosting closure check
(theory.md § 14.5.8) verifies the reductions on every catalogue
open.
The framework is domain-agnostic. The same primitives and analytic views work whether the witness objects are programming languages, processors, cryptographic primitives, file systems, formal systems, ML architectures, or anything else with structure worth cataloguing. See examples.md for domain templates.
See methodology.md for the operational design, tutorial.md for an LLM-friendly walk-through, and cotype/ for the architectural shadow library — including cotype/shadow_risc_core.md which is the authoritative source for the RISC reframe.
Layout
v4cat/
├── __init__.py public API
├── catalogue.py SymmetryCatalogue class (the ISA)
├── views.py kquery + analytic queries
├── mcp_server.py FastMCP server exposing tools/resources/prompts
├── schema.sql generic framework schema (S0-S11)
├── cells.py Cell tagged union + Kinds enum (theory.md § 14.5.1)
├── theory.py framework signature, the IMPL referent (§ 14.5.2)
├── bootstrap.py closure check (§ 14.5.4); SelfHostingViolation
├── framework_seed.sql framework self-cataloguing seed data (§ 14.5.5)
├── methodology.md operational design — ISA, schema, KQUERY, MCP
├── theory.md foundations — shadow architecture, Klein-four, Yoneda+Derrida, magma+pointfree, Theorem 14.5
├── tutorial.md LLM-friendly walk-through, empty → small worked domain
├── examples.md domain templates (languages, processors, crypto, …)
├── mcp_setup.md wire the MCP server into VS Code, Claude Desktop, Claude Code, Codex
├── README.md this file
├── pyproject.toml pip-installable package metadata
└── tests/
├── test_isa.py framework tests, synthetic data
├── test_mcp.py MCP server tests, synthetic data
└── test_self_hosting.py regression test for Theorem 14.5
Documentation
The framework is documented at five levels of depth, plus a setup guide:
README.md(this file): quick start. Installation, layout, first commands.mcp_setup.md: wire the MCP server into VS Code, Claude Desktop, Claude Code, Codex CLI, or any generic stdio MCP client.tutorial.md: walk-through from empty catalogue to a small worked domain. Best first read for an LLM operating the catalogue.methodology.md: full operational design — ISA, schema breaks, the Klein-four read primitive, MCP interface, philosophical lineage.theory.md: foundations — shadow architecture, the temporal axis as normal to symmetry planes, magma + pointfree topology, Yoneda + Derrida, the recursive schema, convergence, trace-thickening.examples.md: domain templates — programming languages, cryptographic primitives, databases, file systems, network protocols, mathematical structures, OS designs, ML architectures.cotype/: the shadow library — the authoritative source for architectural commitments (RISC reframe, migration history, doc-discipline, RFS findings, snap reports). Deep readers should follow this thread; the user-facing docs above reference it where architectural detail exceeds doc grade.
All six user-facing files are exposed as MCP resources at
catalogue://readme, catalogue://mcp_setup,
catalogue://tutorial, catalogue://methodology,
catalogue://theory, and catalogue://examples. There's also
catalogue://docs — an index resource that lists everything
available, suitable as the entry point for an LLM encountering
the framework.
Quick start
from v4cat import SymmetryCatalogue, kquery, agree, blind
with SymmetryCatalogue('/tmp/cat.db') as cat:
# Introduce objects with year + lineage
cat.introduce_object('alpha', 'Alpha', year=1980)
cat.introduce_object('beta', 'Beta', year=1985,
lineage=[('alpha', 'descended-from')])
# Introduce a break with axis classification
cat.introduce_break('F1', 'My first break', axes=['spatial'])
# Witness and refine
cat.witness('alpha', 'F1', 'origin')
cat.witness('alpha', 'F1', 'catalogue-introduces')
cat.witness('beta', 'F1', 'inherits')
cat.refine('F1', 'beta', 'extension', description='details')
# Derived attribution (always a query, never stored)
print(cat.origin('F1')) # → originator: alpha
print(cat.lineage('beta')) # → ancestor chain
print(cat.inherited_breaks('beta')) # → F1 inherited from alpha
# Klein-four read primitive: every read is a comparison
result = kquery(['a', 'b'], ['b', 'c'], universe=['a', 'b', 'c', 'd'])
# {
# '11': ['b'], # both — agreement
# '10': ['a'], # left only
# '01': ['c'], # right only
# '00': ['d'] # shared blindness
# }
Run the MCP server
Two persistence modes, mutually exclusive:
# Pinned-file: server pinned to one SQLite file. Slot tools error;
# the LLM has no string to redirect.
python -m v4cat.mcp_server --db /path/to/cat.db
# Named-slot: server confined to a sandbox directory. Slot tools
# become available; clients address catalogues by slug, never path.
python -m v4cat.mcp_server --root /path/to/dir [--default mydomain]
In named-slot mode the server only ever opens files matching
<root>/<slug>.db, where <slug> is [A-Za-z0-9][A-Za-z0-9_-]{0,63}.
The slug regex rules out .., /, \, leading dots, and NUL bytes;
post-resolve the parent must equal the resolved root, catching
symlink-escape attempts. See v4cat/sandbox.py for the
validation.
Connects via stdio (the standard MCP transport). Configure your MCP-aware client (VS Code, Claude Desktop, Claude Code, Codex CLI, custom agents) to talk to it — see mcp_setup.md for the per-client config snippets.
The server exposes:
- tools: every ISA verb (
introduce_break,introduce_object,witness,refine,defer,promote,boundary,kquery,query_origin,query_lineage, etc.) plus, in named-slot mode,list_catalogues,open_catalogue,create_catalogue. - resources: addressable views (
catalogue://breaks,catalogue://objects/{id},catalogue://retroactive,catalogue://axes,catalogue://lineages/{id},catalogue://self_hosting, ...) - prompts: workflow templates (
analyze_new_object,audit_md_vs_sql,next_object,snap_to_grid_check)
Loading a domain on top
The framework schema (schema.sql) is generic. Domain-specific
schema extensions (per-break detail tables, per-domain views, seed
data) load via load_extension:
cat = SymmetryCatalogue('/tmp/proc.db')
cat.load_extension('path/to/my_domain.sql')
Domain extensions are responsible for their own idempotence
(CREATE TABLE IF NOT EXISTS, INSERT OR IGNORE).
Run the tests
python -m v4cat.tests.test_isa
python -m v4cat.tests.test_mcp
Both use synthetic data only and don't depend on any specific domain. 50 tests; all green on Python 3.13.
Methodology
The brief version:
- Identity is relational (Yoneda). An object is its participation in the witness graph; nothing more.
- Time and lineage are breaks-themselves. A metric field
(e.g. year) and lineage are recorded once per object as primary
data; attribution emerges via tropical MIN over the chosen
axis, restricted to origin-class edges. There's no
RETROverb. - Every read is a comparison (Klein-four).
kquery(A, B; U)classifies the universe into four cells (11,10,01,00).query,wedge,coverage,blindare named selections. - Schema breaks are additive. Don't drop columns; add new ones. The schema's own evolution mirrors the methodology.
- Global structure is always derived, never imposed. Status, origin, retroactive gaps, consistency violations — all live in views.
The full case for these commitments — and their alignment with Derridean traces, Yoneda relationality, and pointfree topology — is in methodology.md.
Naming
The package is v4cat — "the category of V₄-equipped domain
catalogues." The name is licensed by Theorem 14.5 (theory.md § 14)
being operative by default: SymmetryCatalogue(...) runs the
closure check on every open, and the regression test in
tests/test_self_hosting.py passes against every shipped
catalogue. The renaming was triggered by a runtime invariant,
not by an act of nomination — see theory.md § 14.8.
Earlier candidate names from the lifting work, kept here for reference:
kfour/— earlier name committing only to V₄ as the read primitive at level 0, used while the closure check was opt-in.sbc/— Symmetry-Break Cataloguing (descriptive but generic).traces/— Derridean reading.cotype/— after the snap-to-grid accumulator concept.
The MCP URI scheme (catalogue://...) is unchanged: it identifies
addressable catalogue resources by purpose, not by package name.
License
MIT. See LICENSE at the repo root.
Metadata
Release files for v4cat 0.5.0
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 |
|---|---|---|---|---|
| v4cat-0.5.0.tar.gz | 152.8 kB | With provenance | Details for v4cat-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| v4cat-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for v4cat-0.5.0-py3-none-any.whl |
Total release size: 319.7 kB
Release files / v4cat-0.5.0.tar.gz
| Download URL | v4cat-0.5.0.tar.gz |
|---|---|
| Size | 152.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d638f00ddadb13cb057176144a51c977e70dc47fcc254f8ebf412b87a94c01c4
|
|
BLAKE2b-256 checksum How to use checksums |
d3a7adc79d0b26e878e9e7b73f1ab29f61a9de6ae0bf03b5276a6addf919e5f3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 May 4, 2026.
Transparency logRelease files / v4cat-0.5.0-py3-none-any.whl
| Download URL | v4cat-0.5.0-py3-none-any.whl |
|---|---|
| Size | 166.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
44ac8d7cd9da3095c194f0ef0175a50c22d7ef04bfd2aab7353e7fbc1ef7f1e1
|
|
BLAKE2b-256 checksum How to use checksums |
39f77755d6b25e55cba154c95e95977c348ae45d0b3cac16444c67e6621d5ffb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 May 4, 2026.
Transparency logSecurity for v4cat 0.5.0
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 v4cat-0.5.0.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 May 4, 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.