Raygon

Semantic contracts with runtime enforcement and compiler-level introspection.

Raygon is an experimental library that introduces semantic contracts between providers and consumers, focusing on explicit coupling, safe evolution, and runtime guarantees — without schemas, servers, or heavy tooling.

This repository contains the MVP (v0.1.0), proving the core ideas in practice.

---

✨ Core Ideas

Raygon is built around a simple but strict principle:

A consumer should only access what it explicitly declares.

To enforce this, Raygon combines:

• Contracts (semantic definitions of data)
• Runtime Proxies (to track and validate access)
• A Compiler Layer (to analyze usage graphs)

---

🧠 What Raygon Solves

Traditional contracts (DTOs, schemas, interfaces):

• allow silent over-coupling
• break consumers when fields change
• have no runtime awareness of usage

Raygon instead provides:

• Coupling by demand – consumers declare exactly what they use
• Runtime enforcement – accessing undeclared fields is detected
• Safe evolution – new fields do not break existing consumers
• Compiler visibility – usage graphs can be generated statically

---

📦 Packages

This monorepo contains three packages:

@raygon/core

Defines:

• Contracts
• Fields
• Semantic metadata

This package is framework-agnostic and contains no runtime logic.

---

@raygon/runtime

Provides:

• Proxy-based contract consumption
• Runtime validation
• Warnings for invalid or deprecated access

This is where enforcement happens.

---

@raygon/compiler

Provides:

• Static analysis of contracts
• Usage graph generation
• Infrastructure for future tooling (LSP, refactors, etc.)

---

🚀 Example (Basic)

The examples/basic folder demonstrates the MVP in action.

1. Define a contract

// contract.ts
import { Contract, Field } from "@raygon/core";

export const UserContract = new Contract("User", {
  id: new Field("string"),
  fullName: new Field("string"),
  email: new Field("string").optional()
});

2. Consume only what you need

// consumer.ts
import { createContractProxy } from "@raygon/runtime";
import { UserContract } from "./contract.js";

const user = createContractProxy(
  UserContract,
  ["id", "fullName"]
);

console.log(user.fullName);
console.log(user.email); // ❌ runtime warning

3. Runtime output

Raygon runtime: field "email" was accessed but not declared via useContract()

4. Compiler usage

pnpm run compile

---

🧪 Status: MVP (v0.1.0)

This version intentionally focuses on foundations, not features.

✅ Implemented

• Semantic contracts
• Runtime proxy enforcement
• Explicit field usage
• Compiler execution pipeline
• Node ESM support
• Monorepo with project references

❌ Not Yet Implemented

• Automatic refactoring
• IDE / LSP integration
• Source-code analysis
• Persistence or schema servers
• Framework integrations

---

⚠️ Design Constraints (Important)

Raygon intentionally uses:

• Node ESM (NodeNext)
• Explicit .js extensions
• No bundlers
• No magic resolution

This makes the system predictable, portable, and tooling-friendly.

---

🎯 Goals (Future)

• LSP support for semantic refactors
• Contract evolution tracking (aliases, versions)
• Visual dependency graphs
• Compiler-driven breaking-change detection

---

📌 Philosophy

Raygon is not about:

• generating schemas
• validating payloads
• replacing TypeScript

Raygon is about:

making coupling explicit and observable.

---

📜 License

MIT

---

🧩 Disclaimer

Raygon is experimental and intentionally minimal at this stage. The MVP exists to validate the architectural model before expanding the feature set.