Athena

English | Chinese (Simplified)

Athena is the JVM-first implementation workspace for the EngineeringOS semantic compiler thesis.

Name

engineeringood carries two meanings at once:

• engineering good: good for engineering
• OOD: object-oriented development

In EngineeringOS terms, that is the same semantic target expressed another way: engineering meaning should be explicit, structured, composable, and preserved in durable models instead of being trapped inside drawings, files, or tool-specific formats.

Current Scope

The current proof is still architecture-first. It demonstrates that:

• the DSL is the authored source of truth
• Engineering IR is the canonical semantic model
• the compiler owns pass orchestration
• hosted plugins enter through governed source plus approval boundaries
• extensions add domain behavior without becoming semantic authorities
• rendering is a downstream backend, not the source of truth

The implemented scope currently includes:

• a minimal Electrical/Runtime DSL
• parsing into a syntax-only AST
• lowering into canonical Engineering IR
• core semantic validation plus extension-provided domain semantics
• deterministic SVG rendering
• stable hosted plugin API and hosted plugin approval boundaries
• governed knowledge package loading and resolution
• external boundary descriptor validation
• runtime-hosted graph, command, history, diff, and optional AI proposal flows
• real domain-electrical and synthetic domain-dummy proof domains
• a desktop Compose viewer proof and published examples under examples/
• a desktop-first Athena Theia IDE proof with runtime-backed repository sessions, Athena LSP authoring support, and professional workbench panels
• a compiler-derived :kernel:projection-model boundary for renderer-neutral graphical projection documents
• a governed repository/package graph proof with canonical athena.yaml, canonical athena.lock, runtime-owned RepositoryGraphSession, and package-aware IDE feedback
• a VCS-neutral semantic SCM kernel boundary for baseline, diff, consequence, review, commit-intent, and history contracts above :kernel:repository-model
• a deterministic semantic diff layer that compares current and baseline repository/package/engineering meaning through the governed JVM path
• compiler-derived validation and repository-contract consequence publication over the same runtime-owned semantic comparison path
• deterministic semantic review-summary generation that keeps affected packages, authored semantic intent, derived consequences, validation impact, and degraded-input warnings inspectable and traceable
• additive hosted-plugin semantic review enrichment that lets approved plugins append domain labels, hints, and summaries without rewriting core semantic SCM facts
• deterministic semantic commit-intent generation that keeps adapter-ready commit preparation semantic-first, inspectable, and free of Git-specific staging nouns
• package-aware semantic history and release-relevance contracts anchored to stable package identity and version meaning
• runtime/LSP/Theia semantic SCM projection that exposes baseline-driven review, commit-preparation, package evolution, and release-relevance state through the existing Athena workbench without moving semantic authority into the frontend
• the first integrations/graph-glsp translation-only graph adapter boundary that consumes Athena-owned projection-session payloads without adding a second semantic transport
• a unified M8 mutation model where source and graph now share runtime-owned mutation categories, graph semantic mutation proof, graph projection mutation proof, shared semantic review facts, and canonical reveal across source, graph, and semantic SCM

This is not the final UX phase yet.

Module Topology

Athena now groups implementation assets by architectural role. The current JVM/Gradle module graph lives under kernel/, extensions/, ui/, and apps/, while the primary M4 IDE product path now exists as a runnable Theia workspace under ide/.

Group	Module / Seed	Directory	Purpose
ide	node: theia-product	ide/theia-product/	Product composition, packaging, and curated Athena Theia capability set
ide	node: theia-frontend	ide/theia-frontend/	Theia frontend contributions, workbench composition, panels, and commands
ide	node: theia-backend	ide/theia-backend/	Theia backend contributions, startup, path handling, and process orchestration
ide	gradle: :ide:lsp	ide/lsp/	Athena LSP host and JVM semantic-service boundary for the IDE path
integrations	node: graph-glsp	integrations/graph-glsp/	Translation-only graph adapter that keeps GLSP-class protocol and rendering vocabulary downstream of Athena-owned projection sessions
integrations	:integrations:scm-git	integrations/scm-git/	First vendor substrate adapter for semantic baseline loading
kernel	:kernel:language	kernel/language/	Syntax layer and parser for authored DSL text
kernel	:kernel:repository-model	kernel/repository-model/	Canonical M5 repository/package contract boundary for manifest, lock, package identity, and package graph reports
kernel	:kernel:semantic-scm	kernel/semantic-scm/	Canonical M6 semantic SCM contract boundary for baselines, diffs, consequences, typed reviews, commit intent, and package-aware history
kernel	:kernel:engineering-model	kernel/engineering-model/	Canonical engineering model after lowering
kernel	:kernel:layout-model	kernel/layout-model/	Explicit layout projection contracts downstream of canonical semantics
kernel	:kernel:geometry-model	kernel/geometry-model/	Explicit geometry projection contracts downstream of layout intent
kernel	:kernel:projection-model	kernel/projection-model/	Renderer-neutral projection documents derived from layout and geometry for runtime/LSP/graph consumers
kernel	:kernel:validation	kernel/validation/	Generic semantic validation over the canonical model
kernel	:kernel:plugins:plugin-api	kernel/plugins/plugin-api/	Stable hosted plugin SPI, including additive semantic review enrichment contracts
kernel	:kernel:plugins:plugin-host	kernel/plugins/plugin-host/	Plugin source, approval, inventory, and hosted lifecycle boundary
kernel	:kernel:compiler	kernel/compiler/	Compiler facade, lowering, pass orchestration, knowledge, boundary loading, and hosted contribution coordination
kernel	:kernel:runtime	kernel/runtime/	Workspace lifecycle, execution context, graph, command, history, semantic baseline/diff/review/commit, hosted review enrichment, plugin, and AI proposal hosting
kernel	:kernel:svg-renderer	kernel/svg-renderer/	Deterministic SVG projection from semantic state
extensions	:extensions:domain-electrical	extensions/domain-electrical/	First real Electrical domain extension
extensions	:extensions:domain-dummy	extensions/domain-dummy/	Synthetic proof domain for hosted SPI generality
ui	:ui:compose-workbench	ui/compose-workbench/	Shared Compose workbench and viewer interaction infrastructure
apps	:apps:cli	apps/cli/	Shell-facing entry point
apps	:apps:desktop-viewer	apps/desktop-viewer/	Desktop Compose application entry point

Group overviews:

• ide/
• integrations/
• kernel/
• extensions/
• ui/
• apps/

During M5, apps/cli, apps/desktop-viewer, and ui/compose-workbench remain valid proof and verification surfaces, but they are no longer the intended home of the primary IDE product path.

Documentation Scope

The current taxonomy is authoritative in:

• the root and module READMEs
• group READMEs
• DEV.md
• current boundary notes under docs/compiler/
• the active milestone roadmap note under docs/roadmap/

Some compiler docs are intentionally marked as historical references and may preserve story-era labels for context. Historical BMAD artifacts under _bmad-output/ are retained as records and may still use older story labels or earlier module naming.

Build Requirements

• Java 25 is mandatory
• Gradle wrapper: 9.6.1
• Kotlin: 2.4.0

On Windows, run Gradle build, test, and launch tasks sequentially. Do not overlap them in parallel shells.

Quick Start

Unix-like shells:

./gradlew test
./gradlew :apps:cli:run --args="parse examples/m0/demo-cabinet.athena"

Windows PowerShell in this repo:

java25; .\gradlew.bat test
java25; .\gradlew.bat :apps:cli:run --args "parse examples/m0/demo-cabinet.athena"
Set-Location ide
yarn build
yarn start:smoke

java25 is the local workstation helper that switches JAVA_HOME to Java 25 before running Gradle.

For the M6 Athena IDE shell, the Electron wrapper now resolves Java 25 automatically on Windows. Use yarn start:smoke under ide/ as the deterministic desktop-start proof, then yarn start for the live interactive window. The current workbench now includes the additive Semantic SCM panel for baseline-driven review, commit preparation, package evolution, and release relevance. For focused milestone usage, read docs/usages/m5-proof-usage.md and docs/usages/m6-proof-usage.md.

For the finished M8 mutation proof, use docs/usages/m8-proof-usage.md. The current boundary is explicit: graph semantic and graph projection mutation are real accepted paths, while source-originated mutation remains preview-first evaluation plus shared review and reveal coherence.

What To Read

If you want the implementation view:

1. kernel/compiler/README.md
2. kernel/runtime/README.md
3. docs/usages/athena-workspace-summary.md
4. docs/usages/m8-proof-usage.md
5. docs/usages/m6-proof-usage.md
6. docs/usages/m5-proof-usage.md
7. docs/usages/m4-proof-usage.md
8. docs/usages/m3-proof-usage.md
9. docs/compiler/m0-pass-pipeline.md
10. docs/compiler/m1-runtime-host-boundary.md
11. examples/README.md
12. docs/roadmap/athena-milestone-roadmap.md

If you want the platform thesis:

1. manifesto/README.md
2. the architecture and technology chapters under manifesto/docs/

Architecture Notes

• AST is syntax-owned and remains separate from semantic truth.
• :kernel:repository-model is the VCS-neutral repository/package contract boundary for M5 and later SCM work must consume it from above.
• :kernel:semantic-scm is the VCS-neutral baseline/diff/review layer above :kernel:repository-model, and runtime consumes it through the JVM-owned repository session path.
• Engineering IR is the canonical engineering model.
• :kernel:projection-model is the M7 renderer-neutral graphical projection boundary above geometry and below runtime, LSP, and graph adapters.
• Generic validation lives in :kernel:validation; domain validation lives in extensions.
• Plugins are real and discoverable, but non-sovereign.
• Governed knowledge packages and external boundary descriptors are separate from authored project input.

License

See LICENSE.

Reference

1. Deepwiki
2. GitHub Page
3. Github
4. Athena POC
5. Zread