Skip to main content

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:

  1. Identity is relational (Yoneda). An object is its participation in the witness graph; nothing more.
  2. 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 RETRO verb.
  3. Every read is a comparison (Klein-four). kquery(A, B; U) classifies the universe into four cells (11, 10, 01, 00). query, wedge, coverage, blind are named selections.
  4. Schema breaks are additive. Don't drop columns; add new ones. The schema's own evolution mirrors the methodology.
  5. 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)

Source distribution for v4cat 0.5.0
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)

Table of built distributions (wheels) for v4cat 0.5.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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