Cog Language Semantic Model

This document defines the Developer Preview semantic model of Cog. A .cog program does not primarily describe an imperative algorithm; it declares a governed semantic graph together with perspectives, resolution declarations, transformation intent, constraints, emissions, and the execution structure used to inspect and trace that declaration.

1. Semantic Graph

Compilation represents a Cog program as a directed semantic graph whose principal cognitive objects are:

• Entities — named semantic objects with kinds, optional levels, and attributes.
• Relations — directed typed links between entities.
• Views — declared perspectives over entities.
• Resolutions — explicit bindings of targets to Cog levels (L1–L5).
• Transformations — explicit references to governed transformation intent.
• Constraints — explicit constraint declarations attached to targets.
• Emissions — explicit output projections.

The kernel preserves these distinctions rather than collapsing them into an opaque reasoning result.

2. CoreIR

Source passes through lexer and parser stages before compilation into CoreIR. CoreIR is the inspectable intermediate representation consumed by validation, planning, execution, adapters, tools, and traces.

It contains entity, relation, view, resolution, transformation, constraint, emission, and graph structures plus compiler metadata.

CoreIR records declared cognitive structure. It must not be described as evidence that the kernel independently inferred every declared relation, classification, comparison, transformation, or decision.

3. Canonical Consumer Pipeline

The Developer Preview consumer sequence is:

LEX → PARSE → COMPILE → VALIDATE → PLAN → EXECUTE → EMISSIONS + TRACE

executeCog() performs validation and planning internally as well, so direct callers may use it after compilation when they do not require separate inspection of the validation report or plan.

Validation

Core validation currently enforces structural properties such as:

• valid entity references;
• relation source and target existence;
• view target existence;
• valid resolution levels;
• transform and constraint target existence;
• core reference syntax;
• active adapter validation when an adapter provides validateProgram().

An arbitrary rule: string in a .cog constraint is not automatically a general-purpose executable predicate. Domain-specific or cognitive rule evaluation belongs in the appropriate CogLib routine, domain library, adapter, tool, or application layer.

Planning

The planner converts CoreIR into a deterministic execution plan. Kernel plan phases are:

1. bind
2. transform
3. validate
4. emit

Dependencies between plan steps are explicit and inspectable.

Execution

Execution walks the plan, maintains bindings, applies supported adapter hooks, creates emissions, and records a trace.

The kernel transform phase preserves and executes the declared transformation plan step, including its transformation reference. The transform keyword does not by itself imply a universal algorithm capable of deriving arbitrary semantic transformations. Concrete transformation logic must come from the layer that owns that capability.

4. Relations

A relate statement declares that two entities participate in a directed typed relationship.

For example:

relate "current-state" -> "baseline-state" {
  kind: differs-from
}

This declaration says that the relation is part of the governed semantic representation. Whether differs-from was observed, computed, supplied by a CogLib routine, generated by a domain library, or produced by an external tool is a separate provenance question.

Adapters may map neutral relation kinds using mapRelationKind(), but the kernel remains ontology-agnostic.

5. Perspectives

A view declaration associates a target with an explicit perspective identifier:

view "proposal" as operational {
}

The neutral view remains represented in CoreIR. An adapter may project that view to domain-specific terminology through mapViewKind(). The presence of a view does not imply that the kernel automatically performs arbitrary perspective-specific reasoning over entity attributes.

6. Resolutions

A resolution explicitly associates an entity with one of the neutral Cog levels:

resolve "proposal" to L3 {
}

Levels are intentionally domain-neutral in core. An adapter may map them into a domain-specific level system through mapLevel().

A resolution is therefore an explicit governed declaration, not evidence that core independently established the truth or authority of the resolved value.

7. Transformations

Transformations preserve explicit transformation intent:

transform {
  target: "proposal"
  to: assessed
}

Core records the target and transformation reference and includes the step in planning and trace output. Domain-neutral or domain-specific transformation algorithms may be implemented above the kernel.

This separation is deliberate: Cog makes transformations inspectable instead of allowing an implementation to silently change semantic state.

8. Constraints

Constraints attach governance declarations to explicit targets:

constrain {
  target: "proposal"
  rule: "requires-evidence"
}

Core validates structural integrity. A domain layer may additionally interpret and enforce the declared rule through adapter validation or other governed execution mechanisms.

9. Emissions

Emissions are explicit output projections:

emit {
  target: "proposal"
  kind: assessment
}

During execution, the runtime creates an emission payload containing target information and relevant mapped level, view, relation, and attribute data. An adapter may replace or specialize the outbound emission through mapEmission().

Developer Preview examples always specify target: explicitly.

10. Execution Trace

Every executeCog() result includes a trace containing ordered step outcomes and phase information. Traces are first-class evidence about what Cog executed, not a reconstruction performed after the fact.

The trace therefore supports inspection of:

• binding;
• declared transformations;
• validation phase execution;
• emissions;
• adapter-specific trace additions when provided.

11. Architectural Boundary

Cog core owns:

• syntax and parsing;
• CoreIR;
• structural validation;
• deterministic planning;
• runtime execution structure;
• emissions;
• traces;
• adapter contracts.

CogLib, domain libraries, adapters, tools, and applications may supply higher-order cognition and domain semantics.

This boundary is central to the Developer Preview: Cog makes cognition explicit and governable; it does not claim that every cognitive operation named in a graph is automatically inferred by the kernel itself.