Skip to content

LINGUISTIC LAYER SPEC (v1: Normative)

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals, as shown here.

Implementation frontier (2026-08, campaign STRUCT LOT S1). The implemented slice of this spec is the act taxonomy (arvis/linguistic/acts/act_types.py) and the generation frame (arvis/linguistic/generation/generation_frame.py), both consumed by the LLM adapter (arvis/adapters/llm/policy/, arvis/adapters/llm/prompts/). The LinguisticAct object, the gate mapping, the frame builder, the lexicon contract and the linguistic-side prompt builder were design ahead of implementation, never wired into the runtime, and have been removed from the tree; their specification below is retained as the normative design for a future realization layer, and the removed code is in git history.

1. Purpose

The Linguistic Layer defines how a structured response plan is transformed into a realized communicative output.

It operates strictly:

ResponsePlan → Linguistic Representation → Output

It ensures:

  • controlled generation
  • deterministic structure
  • separation between cognition and language
  • safe interaction with generative systems (LLMs or templates)

2. Architectural Position

Cognitive Pipeline
→ Decision (validated)

→ Conversation Layer
→ ResponsePlan

→ Linguistic Layer (THIS)

→ Realization Layer (templates / LLM)
→ Output

IMPORTANT:

The Linguistic Layer operates strictly after IR and ResponsePlan. It MUST treat ResponsePlan as a fully constrained, pre-validated input.

3. Core Principle

The Linguistic Layer does NOT decide what to say.
It determines how to express an already validated intent.
It MUST NOT introduce new semantic content beyond the ResponsePlan.

4. Layer Decomposition

The Linguistic Layer is composed of four subsystems:

1. Act System
2. Generation Frame System
3. Lexicon System
4. Realization System

5. Act System

Definition

Defines the type of communicative act.

Located in:

arvis/linguistic/acts/

Core Object: LinguisticAct

Represents the final communicative intent.

Examples:

  • INFORM
  • ASK_CONFIRMATION
  • REFUSE
  • EXECUTE_ACTION

Constraints:

  • MUST be derived strictly from ResponsePlan
  • MUST be deterministic
  • MUST NOT introduce new semantics

Act Mapping

Defined in:

act_types.py     (implemented: the act taxonomy)
gate_mapping.py  (design only: removed from the tree, see frontier note)

Maps:

ResponseStrategyDecision → LinguisticAct

More precisely:

CognitiveIR → ResponseStrategyDecision → ResponsePlan → LinguisticAct

Invariants

  • MUST be deterministic
  • MUST NOT introduce new reasoning
  • MUST remain consistent with decision + strategy

6. Generation Frame System

Definition

Defines the structured representation of the message before generation.

Located in:

arvis/linguistic/generation/

Core Object: GenerationFrame

Represents:

  • semantic structure
  • content blocks
  • constraints
  • tone and mode

Constraints:

  • MUST be fully derived from ResponsePlan
  • MUST NOT introduce new information

Frame Builder (design only)

Builds:

ResponsePlan → GenerationFrame

Constraints:

  • MUST be deterministic
  • MUST preserve all ResponsePlan constraints exactly

Not implemented: the runtime builds prompts directly from the generation frame through the LLM adapter (arvis/adapters/llm/prompts/builder.py). A dedicated frame builder comes back with the realization layer that needs it.

Responsibilities

  • structure message
  • enforce constraints
  • prepare content for realization

Invariants

  • MUST be deterministic
  • MUST NOT contain final text
  • MUST encode all required structure

7. Lexicon System (design only)

Definition

Provides controlled vocabulary and domain-specific language.

Not in the tree: the lexicon contract (entry and snapshot shapes) was specified and coded ahead of any consumer, and removed as unwired design (see frontier note). This section remains its normative definition.

Contract

The kernel defines the lexicon CONTRACT: what an entry is, and what a snapshot of the active lexicon looks like. It deliberately ships no domain lexicon.

Domain vocabularies (finance, legal, security, ...) are realization: naming what a formal notice or a financial exposure is belongs to the layer that knows the business, not to a domain-agnostic kernel. A realization layer supplies them against this contract.

Role

  • define the terminology contract a realization layer populates
  • carry a versioned snapshot of the active lexicon

Constraints:

  • MUST NOT introduce semantic transformations
  • MUST be a pure normalization layer

Invariants

  • MUST be deterministic
  • MUST be versioned
  • MUST NOT introduce ambiguity

8. Realization System

Definition

Transforms structured representation into final output.

Located in the host layer (there is no realization package inside arvis; see the implementation frontier above).

Components

The implemented path is the LLM adapter: the prompt is built by arvis/adapters/llm/prompts/builder.py against a PromptContract, and driven by the adapter's runtime executor. Turning a structured representation into finished wording, with its templates, is realization and lives in the layer built on top of ARVIS (the linguistic-side prompt builder existed only as unwired design and was removed, see frontier note).

Realization Modes

Defined in:

response_realization_mode.py

Supports:

  • TEMPLATE (deterministic)
  • LLM (controlled generation)

Flow

GenerationFrame → PromptBuilder → LLMExecutor

or

GenerationFrame → Template → Output

Invariants

  • MUST NOT alter decision semantics
  • MUST respect ResponsePlan constraints
  • MUST remain bounded by GenerationFrame
  • MUST be auditable
  • MUST NOT introduce new intent

9. Prompt Builder (LLM Integration)

Role

Constructs a controlled prompt:

GenerationFrame → Prompt

Ensures:

  • no prompt leakage
  • constraint preservation
  • deterministic structure

Constraints:

  • MUST NOT introduce implicit instructions not present in GenerationFrame

Invariants

  • MUST NOT inject new intent
  • MUST preserve all constraints
  • MUST be deterministic given same inputs

10. Separation from Cognition

The Linguistic Layer MUST NOT:

  • perform reasoning
  • modify decisions
  • introduce new information not present in ResponsePlan
  • depend directly on CognitiveState or pipeline internals

11. Determinism Model

Determinism applies at two levels:

Structural Determinism

  • Act
  • Frame
  • Plan

→ MUST be strictly deterministic

Realization Determinism

  • TEMPLATE → deterministic
  • LLM → bounded, but not strictly deterministic

IMPORTANT:

Non-determinism is allowed ONLY in the realization phase.

Even in LLM mode:

  • structure MUST remain deterministic
  • constraints MUST be strictly enforced

12. Auditability

The system MUST allow reconstruction of:

ResponsePlan
→ LinguisticAct
→ GenerationFrame
→ Output

Full traceability chain:

CognitiveIR → ResponsePlan → LinguisticAct → GenerationFrame → Output

13. Relation to Public Objects

Public objects include:

  • ResponsePlan
  • ResponseStrategyDecision

(LinguisticAct was removed from the tree with the unwired linguistic slice; only the LinguisticActType taxonomy survives. See the implementation frontier above.)

These objects MUST comply with ARVIS_PUBLIC_OBJECT.md invariants.

The following are NOT public:

  • GenerationFrame
  • Prompt
  • internal lexicon resolution

14. Security Model

The Linguistic Layer enforces:

  • no uncontrolled generation
  • no leakage of internal state
  • strict constraint adherence
  • no introduction of unauthorized content
  • strict boundary enforcement with IR-derived data only

15. Invariants

  • No decision override
  • No hidden reasoning
  • Deterministic structure
  • Controlled realization
  • Full traceability
  • MUST NOT introduce new semantic content
  • MUST operate strictly post-ResponsePlan