# CogLang

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

Status:

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

Current public language release: `v1.1.0`. Current Python distribution version: `1.1.4`.
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.

When to use CogLang:

- when you want to inspect or approve LLM-generated graph operations before they modify a knowledge graph
- when you need errors to remain explicit values instead of hidden exceptions
- when you need replayable traces for what an agent intended, submitted, and actually executed
- when you want host-side profile and capability checks before execution
- when you need a versioned host-runtime boundary for typed write-envelope submission and response evidence
- when you need a semantic-event audit layer for AI agent graph actions

When not to use CogLang:

- as a general-purpose programming language
- as a schema definition language
- as a claim that it replaces the native query language of a specific graph database
- as a tensor-level interpretability toolkit, routing debugger, metrics backend, or full observability stack

Key design choices:

- canonical M-expression text for parse determinism and inspectable generated structure
- errors as values because partial failure is common in AI-driven graph operations
- profile and capability boundaries so hosts can reject unsafe or unsupported execution paths early
- HRC v0.2 typed write-envelope evidence through `host-demo` and `reference-host-demo`
- non-Python HRC envelope consumption through `examples/node_host_consumer`
- non-Python minimal host/runtime stub evidence through `examples/node_minimal_host_runtime_stub`, without changing HRC v0.2
- a minimal `generation-eval` fixture for checking LLM-generated CogLang outputs against parse, canonicalization, validation, top-level-head, hallucinated-operator, and maturity summaries
- a minimal executor interface: second implementations should start with `execute` and `validate`; Python host-local query/dict/JSON helpers are convenience APIs, not required inheritance surface
- semantic-event audit focus: use CogLang to represent inspectable graph intents and host-visible outcomes, not every low-level model or infrastructure signal

Core documents:

- README.md: public document index and entry points
- CogLang_Quickstart_v1_1_0.md: first-pass guide and common patterns
- 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 promoting Carry-forward, Reserved, or Experimental entries
- 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_4.md: latest Python package patch notes
- CogLang_Release_Notes_v1_1_3.md: previous Python package patch notes
- CogLang_Release_Notes_v1_1_2.md: older Python package patch notes
- CogLang_Release_Notes_v1_1_1.md: older Python package patch notes
- CogLang_Release_Notes_v1_1_0.md: stable language release commitments
- 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, profiles, 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; not stable v1.1 syntax
- CogLang_Contribution_Guide_v0_1.md: contribution boundaries and review expectations
- ROADMAP.md: current direction, not a release contract
- MAINTENANCE.md: maintenance, freeze, transfer, and archive policy

Documentation language policy:

- Public-facing canonical docs are 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.

Short runnable examples:

```powershell
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
```
