> > > SpecLogosFileSpec

Logos File Family Specification

Purpose

This specification defines the common structure and responsibility split of Logos file types. It is the entry point for .model, .view, .api, .interaction, and .fact file-level contracts.

Scope

This document covers:

the purpose of each Logos file family;
common file-level rules;
shared identity, linking, and provenance expectations;
reading order for detailed file specifications.

Non-Goals

This document does not define the full Logos grammar; see LogosLanguageSpec.md.
This document does not define SVO semantics; see LogosSvoSemanticsSpec.md.
This document does not repeat each file type's contract.

Terminology

File type	Responsibility
`.model`	Declarative organizational model and SVO semantic source.
`.view`	Read-side projection intent and scope selection.
`.api`	External API boundary over Logos-modeled capabilities.
`.interaction`	Operational command and UI interaction surface.
`.fact`	Observed or declared fact source for ledger and reconciliation workflows.

Model or Contract

The file family is layered:

.model       -> semantic possibility space
.view        -> read-side projection over model/facts
.api         -> external system boundary
.interaction -> operational command surface
.fact        -> observed or declared occurrence

.model defines the core semantic space. The other file types reference, project, expose, command, or observe that space.

Rules

Every file type must preserve stable identifiers.
Cross-file references must resolve through explicit IDs or declared imports.
A file type may narrow scope but must not redefine the semantics owned by .model.
.view and .interaction are complementary: one projects readable state, the other exposes command intent.
.fact records occurrences or testimony; it does not define the possibility space.
.api exposes stable boundaries and should not leak internal projection implementation.

Examples

process.model       # semantic organization/process model
process.view        # diagram or UI read projection
process.api         # external API contract
process.interaction # command surface for users or agents
process.fact        # observed events or simulation facts

Validation

File-family validation should check:

correct file extension and declared file kind;
stable IDs;
resolvable imports/includes;
no semantic redefinition outside .model;
compatibility between .view and .interaction references;
fact references compatible with the ledger contract.

Compatibility

This document adds an overview layer above existing per-file specifications. It does not replace those specifications.

Open Questions

Should file kind be inferred from extension only, or also declared inside the file?
Should .api and .interaction share a common command schema?

SOTER