Theory files let you collect facts and Sys2DSL programmes into named bundles that can be applied as temporary overlays. They are plain text Sys2DSL scripts: each non-empty, non-comment line (or fragment of a line) is a statement of the form @var ACTION .... This page shows how to structure those files, how they are used by sessions, and how to express both simple and more complex patterns, including references between newly defined variables via $.

Basic Structure

A theory file is a simple text file where each non-empty, non-comment line participates in a Sys2DSL script. Lines starting with # are comments and are ignored. Blank lines are also ignored. The engine does not interpret filenames; only the contents matter, but naming files after their purpose makes them easier to manage.

Example: a minimal health‑compliance theory file health_compliance.sys2dsl:

# Basic procedural requirements for ProcedureX
@req1 ASSERT ProcedureX REQUIRES Consent
@req2 ASSERT ProcedureX REQUIRES AuditTrail

@needs FACTS_MATCHING "ProcedureX REQUIRES ?"
@given FACTS_MATCHING "? GIVEN yes"
@present FACTS_MATCHING "? PRESENT yes"
@allSat MERGE_LISTS $given $present
@decision ALL_REQUIREMENTS_SATISFIED $needs $allSat

Example: a small narrative theory file scifi_magic.sys2dsl that introduces a concept and immediately reuses it via variable references:

# Baseline facts about Alice and CityX
@c1 ASSERT Alice IS_A Human
@c2 ASSERT Alice LOCATED_IN CityX
@magic ASSERT Alice CASTS Magic

@MagicTheory ASSERT SciFi_TechMagic PERMITS Magic_IN CityX
@scenarioFacts MERGE_LISTS $magic $MagicTheory
@maskOntology MASK_PARTITIONS ontology
@check ASK_MASKED $maskOntology "Alice CASTS Magic?"

There is no special syntax for “rules” beyond these Sys2DSL statements. What makes a file a theory is how the engine uses it: it reads all statements and treats their effects as additional context while answering questions or running validations, without permanent changes to long‑term memory unless you also ingest the same facts separately.

Topological Dependencies and $ References

Theory files can express non-trivial dataflows by referencing variables that are defined later in the file. The Sys2DSL engine builds a dependency graph and evaluates statements in a topological order so that all $name references are resolved, as long as there are no cycles.

Example: a theory file that defines a concept and immediately uses it in derived checks, independent of textual order:

# Derived checks first
@bpFact ASSERT Water BOILS_AT Celsius100
@tempFact ASSERT Celsius100 IS_A temperature
@waterPoint BIND_POINT Water
@tempMask MASK_DIMS Temperature
@checkBP ASK_MASKED $tempMask "Water BOILS_AT Celsius100?"

# Definition of reusable bundles below
@waterConcept BIND_CONCEPT Water
@facts FACTS_MATCHING "Water BOILS_AT ?"

Even though @waterConcept appears later in the file, any statement that uses $waterConcept will be executed after its definition. Circular references (for example @a depending on $b and @b on $a) are rejected with deterministic errors.

Using Theory Files via Sessions

At the API level, theory files are loaded as arrays of Sys2DSL lines and passed to a System2Session. The session hands them to the Sys2DSL engine, which executes the statements with topological evaluation and updates the session’s active theory. Separate commands control whether a session theory is persisted to disk or merged into an existing external theory file.

Organising Theories

You can keep theories small and focused, or use them as larger scenario descriptions:

# Minimal theory per domain
health_core.sys2dsl
health_emergency_overrides.sys2dsl
export_eu_us.sys2dsl
narrative_magic_sci_fi.sys2dsl

# Scenario-based theories
scenario_hospital_A.sys2dsl
scenario_hospital_B.sys2dsl
scenario_cityX_festival.sys2dsl

AGISystem2 does not impose a particular naming or directory convention beyond what tooling might expect. It is up to you to decide whether a theory file represents a domain slice (for example, “EU export rules”) or a concrete situation (“the setup of hospital A on a given date”). In both cases, the syntax inside the file is the same: Sys2DSL statements @var ACTION …, possibly using $ references and masks for more complex reasoning.