tjs-lang 0.5.5 → 0.6.5

package/CLAUDE.md

@@ -4,14 +4,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-**tjs-lang** (npm: `tjs-lang`) is a type-safe virtual machine (~33KB) for safe execution of untrusted code in any JavaScript environment. It compiles logic chains and AI agents to JSON-serializable ASTs that run sandboxed with fuel (gas) limits.
+**tjs-lang** (npm: `tjs-lang`) is a typed JavaScript platform — a language, runtime, and toolchain that transpiles TypeScript and TJS to JavaScript with runtime type validation, inline WASM, monadic errors, and safe eval. It also includes AJS, a gas-metered VM for executing untrusted agent code in any JavaScript environment.
 
-Key concept: Code travels to data (rather than shipping data to code). Agents are defined as data, not deployed code.
+**Three pillars:**
 
-**Two languages in one platform:**
-
-- **TJS** — TypeScript-like syntax with runtime type validation for writing your platform
-- **AJS** — Agent language that compiles to JSON AST for safe, sandboxed execution
+- **TJS** — TypeScript-like syntax where types are examples that survive to runtime as contracts, documentation, and tests. Transpiles TS → TJS → JS in a single fast pass.
+- **AJS** — Agent language that compiles to JSON AST for safe, sandboxed execution with fuel limits and injected capabilities. Code travels to data.
+- **Toolchain** — Compresses transpilation, linting, testing, and documentation generation into one pass. Includes inline WASM with SIMD, polymorphic dispatch, local class extensions, and a browser-based playground.
 
 ## Common Commands
 
@@ -70,7 +69,7 @@ npm run functions:serve     # Local functions emulator
 ### Key Source Files
 
 - `src/index.ts` - Main entry, re-exports everything
-- `src/vm/runtime.ts` - All atom implementations, expression evaluation, fuel charging (~2900 lines, security-critical)
+- `src/vm/runtime.ts` - All atom implementations, expression evaluation, fuel charging (~3000 lines, security-critical)
 - `src/vm/vm.ts` - AgentVM class (~226 lines)
 - `src/vm/atoms/batteries.ts` - Battery atoms (vector search, LLM, store operations)
 - `src/builder.ts` - TypedBuilder fluent API (~19KB)
@@ -78,6 +77,7 @@ npm run functions:serve     # Local functions emulator
 - `src/lang/emitters/ast.ts` - Emits Agent99 AST from parsed source
 - `src/lang/emitters/js.ts` - Emits JavaScript with `__tjs` metadata
 - `src/lang/emitters/from-ts.ts` - TypeScript to TJS/JS transpiler with class metadata extraction
+- `src/lang/emitters/dts.ts` - .d.ts declaration file generator from TJS transpilation results
 - `src/lang/inference.ts` - Type inference from example values
 - `src/lang/linter.ts` - Static analysis (unused vars, unreachable code, no-explicit-new)
 - `src/lang/runtime.ts` - TJS runtime (monadic errors, type checking, wrapClass)
@@ -153,8 +153,8 @@ function greet(name: '') -> '' {
 }
 `
 
-const jsCode = tjs(tjsSource)
-// Generates JavaScript with __tjs metadata for runtime validation
+const jsResult = tjs(tjsSource)
+// jsResult.code contains JavaScript with __tjs metadata for runtime validation
 ```
 
 **Full Chain Example:**
@@ -188,6 +188,9 @@ fn('a', 'b') // Returns { error: 'type mismatch', ... }
 - `fromTS` lives in a separate entry point (`tosijs/lang/from-ts`)
 - Import only what you need to keep bundle size minimal
 - Each step is independently testable (see `src/lang/codegen.test.ts`)
+- Constrained generics (`<T extends { id: number }>`) use the constraint as the example value instead of `any`
+- Generic defaults (`<T = string>`) use the default as the example value
+- Unconstrained generics (`<T>`) degrade to `any` — there's no information to use
 
 ### Security Model
 
@@ -223,10 +226,12 @@ AJS expressions behave differently from JavaScript in several important ways:
 - Unit tests alongside source files (`*.test.ts`)
 - Integration tests in `src/use-cases/` (RAG, orchestration, malicious actors)
 - Security tests in `src/use-cases/malicious-actor.test.ts`
-- Language tests in `src/lang/lang.test.ts` (~46KB comprehensive)
+- Language tests split across 14 files in `src/lang/` (lang.test.ts, features.test.ts, codegen.test.ts, parser.test.ts, from-ts.test.ts, wasm.test.ts, etc.)
 
 Coverage targets: 98% lines on `src/vm/runtime.ts` (security-critical), 80%+ overall.
 
+**Bug fix rule:** Always create a reproduction test case before fixing a bug.
+
 ## Key Patterns
 
 ### Adding a New Atom
@@ -376,6 +381,18 @@ Generic Container<T, U = ''> {
     return T(obj.item) && U(obj.label)
   }
 }
+
+// Generic with declaration block (for .d.ts emission)
+// The declaration block contains TypeScript syntax emitted verbatim into .d.ts
+// It is stripped from runtime JS output
+Generic BoxedProxy<T> {
+  predicate(x, T) { return typeof x === 'object' && T(x.value) }
+  declaration {
+    value: T
+    path: string
+    observe(cb: (path: string) => void): void
+  }
+}
 ```
 
 #### Bare Assignments
@@ -692,9 +709,28 @@ The `docs/` directory contains real documentation (markdown), not build artifact
 - `DOCS-TJS.md` — TJS language guide
 - `DOCS-AJS.md` — AJS runtime guide
 - `CONTEXT.md` — Architecture deep dive
-- `AGENTS.md` — Agent workflow instructions (issue tracking with `bd`, mandatory push-before-done)
+- `AGENTS.md` — Agent workflow instructions (issue tracking with `bd`, mandatory push-before-done). **Critical**: work is NOT complete until `git push` succeeds; use `bd ready` to find work, `bd close <id>` to complete
 - `PLAN.md` — Roadmap
 
-### Known Gotcha: Self-Contained Output
+### Known Gotcha: `tjs()` Returns an Object, Not a String
+
+`tjs(source)` returns `{ code, types, metadata, testResults, ... }`. Use `.code` to get the transpiled JavaScript string. This is a common mistake.
+
+### Known Gotcha: Running Emitted TJS Code in Tests
+
+Transpiled TJS code requires `globalThis.__tjs` to be set up with `createRuntime()` before execution:
+
+```typescript
+import { createRuntime } from '../lang/runtime'
+
+const saved = globalThis.__tjs
+globalThis.__tjs = createRuntime()
+try {
+  const fn = new Function(result.code + '\nreturn fnName')()
+  // ... test fn
+} finally {
+  globalThis.__tjs = saved
+}
+```
 
-Transpiled TJS code currently requires `globalThis.__tjs` to be set up with `createRuntime()` before execution. A `{ standalone: true }` option to inline the ~1KB runtime is planned but not yet implemented.
+A `{ standalone: true }` option to inline the ~1KB runtime is planned but not yet implemented.

package/README.md

@@ -272,10 +272,10 @@ The cost of "safe eval"—compare to a 200MB Docker image:
 
 | Bundle                    | Size   | Gzipped   |
 | ------------------------- | ------ | --------- |
-| VM only                   | 42 KB  | **14 KB** |
-| + Batteries (LLM, vector) | 56 KB  | 19 KB     |
-| + Transpiler              | 89 KB  | 27 KB     |
-| Full (with TS support)    | 180 KB | 56 KB     |
+| VM only                   | 218 KB | **66 KB** |
+| + Batteries (LLM, vector) | 14 KB  | 5 KB      |
+| + Transpiler              | 5 KB   | 2 KB      |
+| Full (with TS support)    | 230 KB | 71 KB     |
 
 **Dependencies:** `acorn` (JS parser), `tosijs-schema` (validation). Both have zero transitive dependencies.
 

package/bin/dev.ts

@@ -181,6 +181,7 @@ const server = Bun.serve({
         headers: {
           'Content-Type': contentTypes[ext || 'html'] || 'text/plain',
           'Access-Control-Allow-Origin': '*',
+          'Cache-Control': 'no-cache, no-store, must-revalidate',
         },
       })
     }
@@ -189,7 +190,10 @@ const server = Bun.serve({
     const indexFile = Bun.file(join(DOCS_DIR, 'index.html'))
     if (await indexFile.exists()) {
       return new Response(indexFile, {
-        headers: { 'Content-Type': 'text/html' },
+        headers: {
+          'Content-Type': 'text/html',
+          'Cache-Control': 'no-cache, no-store, must-revalidate',
+        },
       })
     }