SISYF — Systems Integrating System Yielding Formalisms#

Status: Spec exists; code not yet implemented as executable skill.

SISYF is the cross-model compiler for matheology. It reads PoR source files across all models (PET, JUB, and future models) and produces audience-specific downstream pages at multiple depths.

Named after Sisyphus, who pushes his boulder up the hill again and again. Like Sisyphus, SISYF never changes the boulder — it only moves it. Source data is strictly read-only.

Integration flows#

Each topic has its own integration flow. SISYF reads the relevant PoR source from every model that contributes to that topic, and produces compiled views at each depth.

Axioms#

pet/axioms.rst  ──┐
                  ├──→  axioms/expert/     (expert reference)
jub/axioms.rst  ──┤    axioms/easy/       (beginner-friendly)
                  │    axioms/math/       (formal-only)
xyz/axioms.rst  ──┘    axioms/producer/
     ...                axioms/machine/
   (future
    models)

Theorems#

pet/theorems.rst  ──┐
                    ├──→  theorems/expert/
jub/theorems.rst  ──┤    theorems/easy/
                    │    theorems/math/
xyz/theorems.rst  ──┘    ...
     ...
   (future
    models)

Other integration flows#

The same pattern applies to other topics. Not all are yet defined, but candidates include:

  • Symbols — integrated symbol dictionary across all models

  • Logics — the formal frameworks (mereology, modal S5, etc.) used across models

  • Models — overview and comparison of the models themselves

Each flow reads from model-specific PoR sources and writes into the corresponding topic-level depth subdirectories. SISYF never writes into model folders.

Note

FORGE LLog infrastructure: FORGE (the background knowledge compiler) developed a structured session LLog protocol for tracking model development work. If SISYF compilation runs ever need audit trails (e.g., logging which flows ran, what changed, what failed), consider adopting the same infrastructure with a sisyf_ namespace prefix. See FORGE Session Documentation Protocol.

How to run SISYF#

All topics, all depths:

sisyf replace

One topic at specific depths:

sisyf replace --topics axioms --depths expert,easy

One model only (e.g., after editing only JUB sources):

sisyf replace --models jub

Before compiling, SISYF checks that every model it will read has an explicit vvnow field (see VVN gate below). If any model lacks this field, SISYF halts with an error.

Safety profile#

Read-only with respect to all source data. Model folders (pet/, jub/, hell/), the compiler itself, symbols, prior art, and version archives are never modified.

Protected files are never overwritten. Any file whose first comment contains .. compiler:protected is skipped (see DD-b12). This protects human-crafted landing pages (axioms/index.rst, theorems/index.rst) from accidental destruction.

Recovery uses Bouldr (see below), not manual deletion. Never delete output directories by hand — the topic folders (axioms/, theorems/) contain both protected landing pages and regenerable compiled views. Manual deletion risks destroying human-crafted content.

Bouldr — SISYF’s built-in rollback#

Bouldr is the boulder rolling back down the hill — SISYF’s undo mechanism. It is not a separate compiler; it is part of the SISYF cycle.

Before compiling, SISYF takes a Bouldr snapshot of every regenerable depth subdirectory it is about to write to (easy/, expert/, producer/, math/, machine/). The snapshot captures only these subdirectories — never the protected index.rst landing pages above them.

If something goes wrong, bouldr restore replaces the depth subdirectories with the snapshot content. Because the snapshot only contains regenerable content, a restore can never destroy human-crafted files.

sisyf compile    →  [bouldr snapshot] → [compile] → done
bouldr restore   →  depth subdirs restored to pre-compile state
bouldr status    →  shows what changed since last snapshot

Snapshot storage: .sisyf-bouldr/ at the compiler root (gitignored). One snapshot is kept per run; a new compile overwrites the previous snapshot.

Note

Bouldr is not yet implemented. This section defines the intended behavior for when SISYF is built as executable code.

VVN gate#

SISYF must refuse to compile if any model it is asked to integrate does not have an explicit vvnow field set by the human in charge. This prevents the compiler from inventing or guessing version labels. If vvnow is missing from a PoR source file, SISYF halts with an error naming the file and the missing field.

The vvnow field is a model-level field that records the current versioned variant of the model’s content. It is currently implemented as an RST comment (.. vvnow <value>) for Sphinx compatibility, but it is semantically a first-class field of the model.

Where things live#

Open tasks#

  • Implement the spec as executable code

  • Implement Bouldr snapshot and restore

  • Incorporate all hand-edit drift items from the implementation tasks

  • Implement VVN gate (refuse to compile without explicit vvnow)