AYAtlas is an isolated, read-only Architecture Intelligence Platform designed specifically for AykenOS (kenanay/AykenOS). It transforms raw Git repository commits, code files, phase roadmaps, and evidence claims into a Living Governance Knowledge Graph, automated contradiction detector, and continuous CI enforcer.
AYAtlas strictly enforces six non-negotiable constitutional invariants over the AykenOS substrate:
- Read-Only Safety Contract: AYAtlas contains zero mutating/write capabilities targeting the AykenOS repository.
- Mechanism vs Policy Separation: Ring0 kernel execution mechanisms are strictly decoupled from Ring3 policy runtimes.
- Repository Change != Authority Change: Newly detected implementation code does NOT infer or grant active runtime authority (
grantsNewAuthority = FALSE). - Validator PASS != Accepted Evidence: Local validator outputs (proofd/verifier) do NOT equal accepted evidence until exact-subject commit SHA binding and formal governance ratification occur under Phase-24 rules.
- Syscall ABI Freeze: Unauthorized modification of
shared/abiwithout a canonical decision record is flagged asCRITICAL_ABI_FREEZE_VIOLATION. - Deterministic Knowledge Pipeline: 5-Stage data transformations yield time-independent, identical SHA-256 payload digests for the same Git SHA.
AYAtlas is organized as a clean, modular TypeScript monorepo powered by Turbo:
AYAtlas/
├── packages/
│ ├── snapshot-model/ # Pure Repository & Observation Schemas (contentDigest, sourceObjectId)
│ ├── knowledge-model/ # Multi-axial Entity, Relation & Assertion Schemas
│ ├── repository-parser/ # Static Code & Frontmatter Parser (Zero code execution)
│ ├── github-reader/ # Read-Only Repository Adapters (Fixture, Local, GitHub REST API)
│ ├── knowledge-builder/ # 5-Stage Deterministic Knowledge Transformation Engine
│ ├── authority-resolver/ # AykenOS Phase Catalog (Phase-0 -> Phase-24) & Authority Boundaries
│ ├── graph-engine/ # Governance Knowledge Graph Relational Engine
│ ├── repository-ingestor/ # Deterministic File Tree Ingestion & SHA-256 Manifest Generator
│ ├── provenance-engine/ # Exact Source Provenance Tracking & Stale State Invalidations
│ ├── change-intelligence/ # Semantic Diff & Architectural Impact Engine
│ ├── query-engine/ # Audit-Traceable Natural Language Constitutional Answer Engine
│ ├── drift-engine/ # Contradiction & Architectural Drift Inspector
│ ├── architecture-evolution/# Ordered snapshot history & semantic evolution events
│ ├── health-engine/ # Versioned weighted health model with constitutional hard caps
│ └── ci-verifier/ # 5-Gate Constitutional Audit CLI (`npx ayatlas-verify`)
├── apps/
│ └── web/ # React 18 + Vite + Tailwind CSS Dark Glassmorphism Web App
└── docs/ # Constitutional Policies & Isolation Contracts
- Node.js 18+ or 20+
- npm 10+
# Clone the repository
git clone https://github.com/kenanay2020-hub/AYAtlas.git
cd AYAtlas
# Install dependencies across all monorepo workspaces
npm install
# Build all 14 packages and the web application via Turbo
npm run build:allnpm run dev
# Opens the interactive Web Explorer at http://localhost:3000npm test
# Executes the Vitest suite across all workspace packages
npm run test:e2e
# Executes the Chromium end-to-end dashboard flows with Playwrightnpm run verify -- --source fixture --sha d8018a2c3b4a5e6f7a8b9c0d1e2f3a4b5c6d7e8fThe AYAtlas Web Console (apps/web) provides 18 specialized architectural views. All screens display whether their source is deterministic demo data or a live GitHub snapshot.
- Atlas Overview: Substrate metrics,locked SHA, active phase, and high-level component status.
- Architecture Health & Trust Dashboard: Snapshot-derived evaluation of substrate integrity, provenance, ABI observations, and drift findings.
- Architecture Evolution Timeline: Historical trace of invariant additions, capability deprecations, and ABI freezes from Phase-0 to Phase-24.
-
Governance Knowledge Graph: Interactive visual node-edge explorer connecting Substrate
$\rightarrow$ ABI$\rightarrow$ Authority$\rightarrow$ Evidence. -
Constitutional Query Console: Natural language architectural search yielding audit-traceable
ConstitutionalAnswerpackages. - Contradiction & Drift Inspector: Real-time audit of ABI violations, phase pointer mismatches, and unratified code additions.
-
Live Repository Intelligence: Semantic diff comparing base vs target commit SHAs with
grantsNewAuthority = FALSEenforcement. - Evidence Boundary Explorer: 8-Stage evidence verification pipeline and exact-subject SHA binding tracking.
- Phase Explorer: Interactive phase timeline detailing authorized vs forbidden execution scopes.
- Roadmaps: Canonical read-only AykenOS timeline vs editable AYAtlas product roadmap.
- Learning Center: Guided educational paths explaining mechanism vs policy separation and evidence boundaries.
AYAtlas integrates seamlessly with GitHub Actions:
ci.yml: Automatically runsnpm ci,npm run build:all,npm test, andnpx ayatlas-verifyon every commit/PR.ci.ymldeploy job: Automatically builds and deploys the static web bundle (apps/web/dist) to GitHub Pages after verification on pushes tomain.
- Fixture is deterministic demo data and is always labelled as such.
- GitHub reads the public AykenOS repository through GET-only API calls with timeouts, retries, rate-limit diagnostics, and truncated-tree reporting.
- Local is intentionally Node/CLI-only because a static browser application cannot safely access arbitrary filesystem paths. Use
npm run verify -- --source local --path /path/to/AykenOS.
This project is governed by the AYAtlas Constitution and Read-Only Contracts: