Logos Model File Spec

Purpose

This specification defines the file-level contract for .model files: the canonical element-definition rule, the composition mechanism for building one logical model from several files, and the dependency boundary that keeps .model files from absorbing concerns that belong to .view, .interaction, or .fact files.

.model is the ontology/physics layer: it defines what can exist or happen, not what has happened (.fact) or how it is observed or operated (.view/.interaction).

Scope

This document covers:

• the canonical element u-uuid() definition line and why the technical identifier must remain stable and solitary;
• the include directive for composing one logical model from several physical files;
• the dependency rule that bounds what a .model file may reference and must not define.

Non-Goals

• This document does not define the base Logos lexical grammar (indentation, headers, comments, attributes, aliases); see LogosLanguageSpec.md.
• This document does not define the SVO element types (Subject, Object, Action, Relationship) that populate a .model file; see LogosSvoSemanticsSpec.md and PhilosophyConstitution.md.
• This document does not define .view, .interaction, .fact, or .api file contracts; see LogosViewFileSpec.md, LogosInteractionFileSpec.md, LogosFactFileSpec.md, and LogosApiFileSpec.md.

Terminology

Model or Contract

Canonical Element Definition Line

The only permissible line defining a Logos element inside a .model file is:

element u-uuid()

• We do not use the form element SemanticId(uuid).
• The technical identifier is always followed by empty parentheses ().
• No comment is allowed at the end of the definition line.

Composition via include

include "path/to/file.model"

The include directive enables merging multiple smaller model files into a single, cohesive executable entity. File hierarchy resolution occurs during the load step, protecting designers from "single giant file hell."

Dependency Boundary

Rules

• SOTER assumes a model exists in statu nascendi: it matures from initial, often imprecise or even incorrect analytical hypotheses to subsequent, more accurate representations. The SemanticId may change as the model's meaning matures.
• If the SemanticId were located in the element's own definition line, every such change would obscure traceability and degrade the readability of Git commits. The technical identifier must therefore remain stable, solitary, and unambiguous.
• A .model file must not define view, interaction, or fact concepts. Those belong in their own file kinds and are composed with .model through reference, not inline definition.
• Every element defined in a .model file must use a UUID or LIBERAL_ID technical identifier per the base Logos grammar; see LogosLanguageSpec.md for identifier syntax and Auto-UUID transformation.

Examples

Composing a model from smaller files:

include "shared/parties.model"
include "shared/contracts.model"

Canonical element definition line (correct):

element u-3f9a1b2c-1234-4a1b-9c1d-000000000001()
    name: Contract

Incorrect (semantic id embedded in the definition line, not permitted):

element Contract(u-3f9a1b2c-1234-4a1b-9c1d-000000000001)

Validation

The parser and strict-mode linter enforce the canonical element definition line and reject definitions that embed a SemanticId in place of, or alongside, the technical identifier. include resolution is validated at load time; unresolved includes are a fatal error.

Compatibility

Related Documents

• LogosLanguageSpec.md - base Logos lexical grammar that .model files are written in.
• LogosFactFileSpec.md - the ledger counterpart to .model.
• SOTER_MVP.md - complete guide to SOTER MVP CLI and Local Ledger.
• ManualAnalyst.md - Analyst & Modeler Manual for Logos DSL.