> > > SpecLogosApiFileSpec

Logos Api File Spec

Purpose

This specification defines the current status of .api files: the machine-to-machine (M2M) integration membrane through which external specialized systems (e.g. FK, HR, MES) integrate with SOTER. It exists so that .api's provisional status is documented explicitly rather than left implicit.

Scope

This document covers:

the current (temporary) semantic and architectural status of .api;
the conceptual role .api plays in SOTER's CQRS-of-Reality file separation;
what remains open before .api gets its own dedicated specification.

Non-Goals

This document does not define a dedicated M2M membrane grammar, protocol, or authentication/authorization model — none exists yet.
This document does not redefine .interaction; see LogosInteractionFileSpec.md, which .api currently mirrors.
This document does not define the base Logos lexical grammar; see LogosLanguageSpec.md.

Terminology

Term	Meaning
`.api`	The M2M membrane file kind through which external systems integrate with SOTER.
M2M	Machine-to-machine: integration between SOTER and external specialized systems, as opposed to human-facing UI.
External specialized system	A system such as FK (financial/accounting), HR, or MES that runs as a Subject on top of SOTER and integrates through `.api`.

Model or Contract

Until revoked, .api is semantically and architecturally identical to .interaction. All current model, validation, and implementation decisions for .api should be treated as a mirror image of .interaction until a separate specification for the M2M membrane is written.

.api is one of SOTER's five file kinds under the CQRS of Reality axiom:

.model        - Ontology / Physics
.view         - Read
.interaction  - Write
.fact         - Ledger
.api          - M2M membrane

External specialized systems (FK, HR, MES) run as Subjects on top of SOTER and integrate through the .api membrane, rather than SOTER absorbing their domain logic directly. SOTER is not a monolithic ERP; .api is the boundary that keeps it from becoming one.

Rules

Treat every current model, validation, and implementation decision made for .interaction as applying equally to .api, until this document is superseded by a dedicated M2M membrane specification.
Do not introduce .api-specific grammar, keywords, or validation rules ahead of that dedicated specification — doing so would fork a boundary that is deliberately being kept identical to .interaction for now.

Examples

None. .api files currently follow the same examples documented in LogosInteractionFileSpec.md.

Validation

.api files are validated using the same rules as .interaction files until a dedicated specification exists.

Compatibility

This mirror-of-.interaction status is explicitly temporary ("until revoked"). Any change to this status, or introduction of .api-specific grammar, is a compatibility-relevant event and should be recorded as an ADR per the CQRS of Reality axiom in PhilosophyConstitution.md.

Open Questions

When should a dedicated M2M membrane specification be written, and what should trigger that work (e.g. the first external system integration that needs .api-specific behavior .interaction does not have)?
Should .api eventually diverge from .interaction in authentication, authorization, or payload framing, given that its callers are external systems rather than human users?