cog Developer Preview
cog is a small declarative language and execution substrate for constructing governed semantic graphs with explicit entities, relations, perspectives, resolutions, transformations, constraints, emissions, validation, planning, and execution traces.
Canonical documentation
Explore the complete canonical documentation suite. Every guide is calibrated to tested language behavior, executable canonical fixtures, and the eight-command developer toolbelt.
The shortest path from a clean folder to a working Cog program.
Learn the seven .cog statement families and ten recurring cognitive patterns.
Build a complete governed cognitive structure across the full Developer Preview language surface.
Unix-inspired developer tools for inspecting, linting, graphing, tracing, and comparing Cog programs.
Application capstone examining five canonical cognitive architectures.
Canonical public authoring profile for the Cog language and grammar.
Governed semantic graphs, CoreIR intermediate representation, and runtime execution pipeline.
Ratified teaching contract and cognitive-responsibility boundaries for the Developer Preview.
Execution pipeline
Every execution passes through deterministic planning phases:
Every runtime execution returns an inspectable trace and explicit emissions.
Responsibility boundary
The kernel preserves governed declarations and execution structure. Higher-order cognitive algorithms are supplied by CogLib, domain libraries, adapters, tools, or applications.
Quick start
The Developer Preview targets Node 20 and npm 10 or newer. Use npx --no-installfor project-local CLI execution without global installation.
1 · Install
npm install @winmedia/cog-corePackage: @winmedia/cog-core. The release package exposes the core language, packaged curriculum in learning/, and executable examples/.
2 · Inspect
npx --no-install cog help
npx --no-install cog discover
npx --no-install cog workflowsDiscovery matters because libraries and workflow capabilities should be read from the installed release rather than assumed from documentation.
3 · Write
observation.cogStart with one explicit observation and one emission. The point is not the ambient-light example; it is learning the shape of a cognitive object that can be validated and executed.
define entity "observed-signal" {
kind: observation
level: L1
operation: observe
attribute: "ambient-light"
value: "present"
confidence: 1
}
emit {
target: "observed-signal"
kind: observation
}4 · Validate, then run
npx --no-install cog validate observation.cog
npx --no-install cog run observation.cogKeep validation before execution as the default habit. A cognitive program should fail visibly when its structure or semantics are not valid.
Language Grammar
Cog does not currently include loops, functions, imports, macros, or hidden control flow. Every Developer Preview program is composed from these seven explicit statement families:
| Statement | Structural Role & Purpose |
|---|---|
| define entity | Declare an addressable semantic object with kinds, levels, and explicit attributes. |
| relate | Declare a typed directed relationship between two entities. |
| view | Declare a perspective or projection on an entity. |
| resolve | Bind an entity or target to a Cog resolution level (L1–L5). |
| transform | Declare transformation intent for an explicit target. |
| constrain | Attach an explicit governed constraint rule to a target. |
| emit | Declare an explicit output target and emission kind. |
CLI reference
The CLI exposes a compact Unix-inspired developer toolbelt for inspecting, linting, graphing, tracing, and comparing .cog programs without needing a TypeScript harness.
| Command | Purpose |
|---|---|
| cog help | Show the installed command surface. |
| cog discover | List available domain capability libraries. |
| cog workflows | List runnable workflow definitions available to the installed release. |
| cog validate <file> | Parse and validate a .cog program without executing it. |
| cog run <file> | Execute a validated .cog program. |
| cog lint <file> | Find structural workflow smells before execution. |
| cog graph <file> | Render compiled semantic structure as Mermaid flowchart. |
| cog trace <file> [--phase <phase>] | Inspect the execution path, step order, and plan phases. |
| cog diff <before> <after> | Compare execution traces between two running .cog programs. |
Beginner's guide
Do not begin with the largest domain workflow. Learn the grammar of cognitive operations, learn to compose them in the Governed Decision tutorial, use the Level-2 developer toolbelt, then study the Level-3 application architectures.
Level 1
Begin with the seven statement families and ten canonical cognitive patterns: observation, identification, comparison, classification, relation, projection, resolution, constraint, transformation, and emission.
Outcome: You should be able to read a small .cog file and explain what cognitive operation each statement represents.
Governed Decision
Compose the full language surface into one complete problem: evidence, perspectives, resolution, transformation, constraints, and emissions.
Outcome: You should be able to write an end-to-end governed cognitive decision program.
Level 2
Use the eight-command Developer Preview toolbelt: discover, workflows, validate, lint, graph, run, trace, and diff.
Outcome: You should be able to inspect, lint, graph, and compare cognitive execution traces from the command line.
Level 3
Study five canonical application architectures: research synthesis, editorial document review & drift detection, decision analysis, audit reasoning, and knowledge graphs.
Outcome: You should be able to choose a domain library, adapt an example, validate it, and run a bounded cognitive workflow.
Examples
The repository groups canonical examples into primitives, pipelines, graphs, adapters, and applications. Start with primitives; use application examples when you are ready to see several operations composed into a domain workflow.
Primitive set
Observation, identification, relation, classification, comparison, constraint, transformation, resolution, projection, and emission each have small canonical examples in the repository.
Observe sources, extract claims, compare them, cluster them, resolve the synthesis, and emit a final result.
Read the canonical example →Use a bounded workflow for document review, drift detection, reconciliation, and explanation.
Read the canonical example →Represent alternatives, constraints, evaluation, and resolution as an inspectable cognitive workflow.
Read the canonical example →Model findings, relations, severity, and audit resolution without hiding reasoning structure inside prose.
Read the canonical example →Identify nodes and profiles, relate them, form clusters, and emit explanatory correlation structures.
Read the canonical example →Standard Library
Run cog discover against the installed release for the authoritative list. The Developer Preview library family is organized around reusable domains rather than one giant general-purpose workflow.
Research Synthesis
cog:domain:research
Editorial Review
cog:domain:editorial
Decision Analysis
cog:domain:decision
Audit Reasoning
cog:domain:audit
Knowledge Graph
cog:domain:graph
Human Orientation
cog:domain:orientation
Cognitive Ecology
cog:domain:cognitive-ecology
Devotional Intelligence
cog:domain:devotional-intelligence
Reference & Authorities
Developer Preview Teaching Surface — ratified teaching contract, authority hierarchy, and responsibility boundaries.
WinMedia cog framework — what cog means and why its cognitive structure matters.
GitHub source — implementation, examples, tests, issues, and release code.
@winmedia/cog-core on npm — the package destination for the Developer Preview.
Developer Preview boundary