# CogLang

CogLang is a graph-first intermediate language designed for LLM-generated graph queries and updates, with auditable execution under explicit host contracts.

It is best understood as a language layer that can sit between a language model and a graph-backed system without losing the ability to inspect, replay, deny, or trace what is about to happen.

Current status:

- stable `v1.1.0` language core
- reference implementation
- active experimental maintenance for host/runtime ecosystem work
- HRC v0.2 frozen only for the narrow typed write-envelope host bridge

Current public language release: `v1.1.0`. Current Python distribution version: `1.1.3`.
HRC v0.2 is frozen for the narrow typed write-envelope surface demonstrated by `coglang host-demo` and `coglang reference-host-demo`. A minimal Node.js standard-library consumer under `examples/node_host_consumer` reads the HRC schema pack and envelope samples without importing the Python runtime. An experimental in-repository Node.js minimal host/runtime stub under `examples/node_minimal_host_runtime_stub` is post-freeze example evidence, not an HRC scope expansion.

This file is for LLM-oriented retrieval and summarization. It is not the release contract. For package patch notes, use `CogLang_Release_Notes_v1_1_3.md`; for stable language commitments, use `CogLang_Release_Notes_v1_1_0.md`.

## What CogLang Is For

Use CogLang when:

- you want an LLM to generate graph queries or updates, but you do not want to execute raw model output without inspection
- you want a structured language where errors remain explicit values instead of hidden exception-driven control flow
- you want replayable traces showing what an agent intended, what was submitted, and what actually executed
- you want host-side profile and capability checks to reject unsafe or unsupported operations before execution
- you need a versioned host-runtime boundary for typed write-envelope submission and response evidence
- you want a small public fixture for checking whether generated CogLang text parses, canonicalizes, validates, uses expected top-level heads, and avoids hallucinated operators

## What CogLang Is Not For

Do not use CogLang when:

- you need a general-purpose programming language
- you need a schema definition language
- you only need the native query language of a specific graph database in its native setting
- you want a universal superiority claim that one graph language is better than another
- you need tensor-level mechanistic interpretability, routing attribution, metrics dashboards, or a full observability backend

CogLang intentionally avoids framing itself as a competitive replacement for every graph query language. Its public position is design intent, not superiority claims.

## Interpretability And Audit Fit

CogLang fits the role of a semantic-event audit layer: it can represent what an
AI system intended to query or update in a graph, what was submitted to a host,
what the host accepted or rejected, and what traceable result came back.

CogLang is not a complete interpretability stack. It should usually be paired
with other tools for lower-level or broader signals:

- structured logs or tracing systems for process lineage and service-level telemetry
- metrics systems for aggregate behavior and dashboards
- model analysis, probes, or intervention experiments for tensor-level or causal interpretation
- routing logs for why an agent or workflow selected a particular path

The useful boundary is: use CogLang when the event can be expressed as an
inspectable symbolic graph intent or host-visible graph outcome. Use other
systems for raw activations, infrastructure telemetry, routing scores, and
causal intervention results.

## Key Design Choices

1. Canonical M-expression text

CogLang uses a stable M-expression style instead of relying on loose surface syntax. The goal is parse determinism, canonicalization, and inspectable generated structure for LLM-produced programs.

2. Errors as values

CogLang keeps failures explicit in the language model rather than defaulting to exception-driven control flow. This is important because partial failure is common in AI-driven graph operations.

3. Profile and capability boundaries

CogLang keeps profile and capability checks near the language boundary so a host can reject unsupported or unsafe execution paths before they run.

4. Trace and auditability

CogLang treats traces and correlated local write views as first-class host concerns. The point is not only to execute an operation, but to preserve enough structure to inspect and replay it.

5. Feature-tier discipline

CogLang separates `Core`, `Reserved`, and `Experimental` capabilities so stable commitments and exploratory work do not blur together.

6. Inspectable expression values

CogLang expression values are expected to remain suitable for canonical text, readable rendering, hashing, diffing, and replay. Large opaque host-owned payloads should normally be represented by references plus metadata rather than embedded as raw bytes.

7. Minimal executor surface

The abstract `CogLangExecutor` surface is intentionally small. A second
implementation should start with `execute(expr)` and `validate(expr)`. Optional
write-candidate hooks may be overridden, but their default behavior is safe for
minimal executors. Python host-local helpers such as local write queries,
dict/JSON view variants, and submission-id lookup conveniences belong to
`PythonCogLangExecutor` and host tooling; they are not required inheritance
surface for every implementation. `coglang release-check` includes an
`executor_interface` gate to keep this boundary visible.

8. Non-Python example evidence

`examples/node_host_consumer` shows that Node.js standard-library tooling can
read the HRC schema pack and envelope samples. `examples/node_minimal_host_runtime_stub`
adds a small in-repository Node.js stub for tiny `execute` / `validate` behavior
and typed write-envelope success/failure paths. It is companion evidence, not a
new frozen HRC requirement.

## Good Matching User Intents

User intent:

"I need to inspect LLM-generated graph updates before they run."

CogLang fit:

"CogLang is an intermediate language that lets you inspect and approve LLM-generated graph operations before they modify your graph."

User intent:

"I want a language my model can use to query and update a knowledge graph without hiding failures."

CogLang fit:

"CogLang is designed for LLM-written graph queries and updates, with error-as-value semantics and explicit host-side boundaries."

User intent:

"I need to trace what an AI agent intended versus what it actually executed."

CogLang fit:

"CogLang keeps replayable traces and correlated request/response/query views so you can diff intent, submission, and execution."

## Short Runnable Examples

```powershell
coglang execute 'Get["einstein", "label"]'
coglang execute 'Query[n_, Equal[Get[n_, "category"], "Person"]]'
coglang execute 'IfFound[Traverse["einstein", "born_in"], x_, x_, "unknown"]'
coglang preflight --format text 'AllNodes[]'
coglang generation-eval --summary-only
coglang demo
coglang host-demo
coglang reference-host-demo
node examples/node_host_consumer/consume_hrc_envelopes.mjs
node examples/node_minimal_host_runtime_stub/run_demo.mjs
```

## Generation Evaluation Evidence

`coglang generation-eval` runs the packaged minimal fixture for LLM-generated
CogLang outputs. It is not a public benchmark claim. It is a deterministic local
check that reports parse, canonicalization, validation, expected top-level-head,
hallucinated-operator, per-level, maturity, and failure-case summaries.

Useful modes:

```powershell
coglang generation-eval --summary-only
coglang generation-eval --failures-only --answers-file answers.json
coglang generation-eval --format text
```

The default fixture currently contains 50 cases. `coglang release-check` verifies
that the packaged fixture is present and loadable.

## Document Entry Points

- `README.md`
  Public document index and entry points.
- `CogLang_Quickstart_v1_1_0.md`
  First-pass guide, common patterns, and common mistakes.
- `CogLang_Specification_v1_1_0_Draft.md`
  Language semantics.
- `CogLang_Conformance_Suite_v1_1_0.md`
  Executable examples and regression boundaries.
- `CogLang_Profiles_and_Capabilities_v1_1_0.md`
  Profile and capability boundaries.
- `CogLang_Operator_Catalog_v1_1_0.md`
  Operator status and call-surface summary.
- `CogLang_Reserved_Operator_Promotion_Criteria_v0_1.md`
  Evidence bar for moving `Carry-forward`, `Reserved`, or `Experimental` entries toward a more stable surface.
- `CogLang_Send_Carry_Forward_Exit_Matrix_v0_1.md`
  `Send`-specific promotion or downgrade evidence matrix; not a cross-instance protocol freeze.
- `CogLang_Readable_Render_Boundary_v0_1.md`
  Boundary between canonical text, display-only readable rendering, and structured transport envelopes; not a renderer implementation.
- `CogLang_Readable_Render_Golden_Example_Candidates_v0_1.md`
  Candidate readable-render examples and invariants for future renderer work; not stable renderer output.
- `CogLang_Readable_Render_API_Promotion_Checklist_v0_1.md`
  Gates for promoting readable-render candidates into a public API or CLI surface; not a renderer implementation.
- `CogLang_HRC_Companion_Asset_Classification_v0_1.md`
  HRC formal versus companion asset classification; not an HRC scope expansion.
- `CogLang_Standalone_Install_and_Release_Guide_v0_1.md`
  Install, build, and local release verification.
- `CogLang_Host_Runtime_Contract_v0_1.md`
  Minimal host contract.
- `CogLang_HRC_v0_2_Final_Freeze_2026_04_28.md`
  Host-runtime contract v0.2 frozen scope and evidence.
- `CogLang_HRC_v0_2_Freeze_Candidate_2026_04_28.md`
  Prior freeze-candidate review record.
- `CogLang_Release_Notes_v1_1_3.md`
- `CogLang_Release_Notes_v1_1_2.md`
- `CogLang_Release_Notes_v1_1_1.md`
- `CogLang_Release_Notes_v1_1_0.md`
  Current promises and non-promises.
- `CogLang_Vision_Proposal_v0_1.md`
  Long-term capability proposal, including v1.2 candidate themes, graph-compute governance, and AI learning maturity.
- `CogLang_v1_2_Evolution_Boundary_Proposal_v0_1.md`
  v1.2 planning boundary for semantic-action evolution, Core stability, profile contract packs, effect preflight, graph budgets, and review bundles.
- `CogLang_v1_2_Effect_Budget_Preflight_Vocabulary_v0_1.md`
  Minimal v1.2 vocabulary candidate for EffectSummary, GraphBudget, GraphBudgetEstimate, PreflightDecision, and budget-related errors. These names are proposal material, not stable v1.1 syntax.
- `CogLang_Contribution_Guide_v0_1.md`
  Contribution boundaries and review expectations.
- `ROADMAP.md`
  Current direction layer, not a release guarantee.
- `MAINTENANCE.md`
  Maintenance, freeze, transfer, and archive policy.

## Documentation Language Policy

Public-facing canonical documentation is English-first. Chinese companion translations may appear as `.zh-CN.md` files. If an English document and a translation disagree, the English document, executable conformance suite, and implementation tests take precedence.

## One-Sentence Summary

CogLang is a stable v1.1 language core and reference implementation for auditable LLM-produced graph operations: the kind of language you can place between a language model and a graph-backed system without losing the ability to inspect, replay, or deny any given step. Host Runtime Contract and ecosystem work remain versioned separately and narrower than a complete host platform.
