Project Philosophy

TypeScript-Shaped, With an Explicit Boundary

Imported .ts and .js preserve host behavior. A .vibe file uses a TypeScript-derived grammar plus VibeLang semantic checks and lowering. This boundary permits must-use Results, Promise-chain restrictions, capability inference, and static durable planning without pretending that all JavaScript already obeys those rules.

Expected Failures Are Values

VibeLang uses Result<A, E> and Promise<Result<A, E>> as ordinary runtime types. The compiler makes them pleasant to author:

function loadConfig(
  path: string,
): Result<Config, FileNotFound | InvalidConfig> {
  const fs = FileSystem.context()
  const source = fs.readText(path).unwrap()
  return Config.parse(source).unwrap()
}

Plain success returns and Error throws are lifted into the appropriate variant. .unwrap() propagates. Public APIs use normal generic return types, so tools do not need to understand an erased failure annotation.

Optional<T> uses the same philosophy for absence: normal type, normal calls, and compiler-assisted lifting without optional-specific grammar.

Inference Inside, Contracts at Boundaries

The compiler may infer success/error unions and context requirements from a body. Exported APIs should spell their Result return type explicitly. Requirements arise from compiler-recognized Capability.context() calls and continue to propagate statically until a Layer supplies them.

Imported Intrinsics, Not Keywords

Compile-time and durable semantics are anchored by resolved imports:

import { comptime } from "vibelang:comptime"
import { durable } from "vibelang:flows"

This keeps code visually close to TypeScript, allows aliases, and avoids reserving words. Import identity—not spelling alone—activates the compiler behavior.

Platform Is a Dependency

Filesystem, network, clocks, randomness, environment variables, and host globals differ across targets. Modeling them as capabilities gives production configuration, deterministic testing, and portability one mechanism.

Comptime Is Hermetic

comptime(...) may generate values, types, validators, and loaders, but it cannot silently observe ambient filesystem state, the network, the clock, or randomness. External compiler inputs arrive through tracked imports or loader contexts. Durable planning is separate static lowering initiated by durable(...); a Flow is never run to discover its graph.

Standard Imports for Non-Code Inputs

Assets and foreign source use import attributes instead of new grammar:

import config from "./config.json" with { type: "json", mode: "const" }
import prompt from "./prompt.mdx" with { type: "mdx" }

The loader and every string-valued attribute become part of the reproducible build node.

Backend-Appropriate Compilation

The TypeScript backend should preserve the stock pipeline wherever possible. Native and Wasm backends may use whole-program information and shared checked IR. Durable builds may partition a coordinator and worker artifacts. Semantics remain consistent even when emitted machinery differs.

One Toolchain

The long-term product follows Go's shape: compiler, formatter, language service, tests, standard library, and build integration as one coherent distribution. The implementation is a minimal-diff TypeScript fork with narrow VibeLang seams.