tjs-lang 0.8.1 → 0.8.3

package/CLAUDE.md

@@ -86,6 +86,8 @@ bun run functions:serve     # Local functions emulator
 - `src/lang/inference.ts` - Type inference from example values
 - `src/lang/json-schema.ts` - JSON Schema generation from TypeDescriptors and example values
 - `src/lang/linter.ts` - Static analysis (unused vars, unreachable code, no-explicit-new)
+- `src/lang/predicate.ts` - Predicate-safety verifier: certifies a cluster of pure, synchronous, composable predicates (reads the atom `effects` tag via `effectfulFromAtoms`); verified predicates compile to native JS. Also `suggest()` — mines a cluster for autocomplete completions (keyword sets → `value`s, `startsWith` guards → open-ended `stub`s like `var(--`; mined values run through the compiled predicate so they're guaranteed valid). Exported from `tjs-lang/lang`. See `experiments/predicates/` (CSS torture set + perf + suggest demo)
+- `src/lang/predicate-schema.ts` - Predicate-aware JSON-Schema: the `$predicate` keyword (computational types). `compilePredicateSchema`/`validatePredicateSchema` — structure for naive validators, `$predicate` for aware ones (progressive enhancement). The serializable-into-JSON-Schema endgame; exported from `tjs-lang/lang`
 - `src/lang/runtime.ts` - TJS runtime (monadic errors, type checking, wrapClass)
 - `src/lang/wasm.ts` - WASM compiler (opcodes, disassembler, bytecode generation; multi-function module composition; wasm-to-wasm `call <index>` resolution)
 - `src/lang/emitters/js-wasm.ts` - JS bootstrap emitter for compiled wasm modules (one `WebAssembly.compile` per file, name→export-index table, type-aware wrappers)
@@ -113,7 +115,11 @@ createAgent(source, vm)     // Creates callable agent
 
 // VM
 const vm = new AgentVM(customAtoms)
-await vm.run(ast, args, { fuel, capabilities, timeoutMs, trace })
+await vm.run(ast, args, {
+  fuel, capabilities, timeoutMs, trace,
+  costOverrides: { atomOp: 5 },             // per-atom fuel cost override
+  timeoutOverrides: { atomOp: 60_000 },     // per-atom wall-clock override (ms; 0 disables)
+})
 
 // Builder
 Agent.take(schema).varSet(...).httpFetch(...).return(schema)
@@ -208,7 +214,7 @@ fn('a', 'b') // Returns { error: 'type mismatch', ... }
 **Design Notes:**
 
 - The two steps are intentionally separate for tree-shaking (TS support is optional)
-- `fromTS` lives in a separate entry point (`tosijs/lang/from-ts`)
+- `fromTS` lives in a separate entry point (`tjs-lang/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`
@@ -249,7 +255,7 @@ 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 split across 17 files in `src/lang/` (lang.test.ts, features.test.ts, codegen.test.ts, parser.test.ts, from-ts.test.ts, wasm.test.ts, etc.)
+- Language tests split across 18 files in `src/lang/` (lang.test.ts, features.test.ts, codegen.test.ts, parser.test.ts, from-ts.test.ts, wasm.test.ts, etc.)
 - LLM integration tests (run via full `bun test`, skipped by `SKIP_LLM_TESTS`) need a local **LM Studio** server with a chat + embedding model loaded. Setup and the hard-won gotchas (model load failures, leaked-VRAM stray `node` worker, updating runtimes, CORS, the audit-cache parallel race) are in [`docs/lm-studio-setup.md`](docs/lm-studio-setup.md).
 
 Coverage targets: 98% lines on `src/vm/runtime.ts` (security-critical), 80%+ overall.
@@ -260,7 +266,7 @@ Coverage targets: 98% lines on `src/vm/runtime.ts` (security-critical), 80%+ ove
 
 ### Adding a New Atom
 
-1. Define with `defineAtom(opCode, inputSchema, outputSchema, implementation, { cost, timeoutMs, docs })`
+1. Define with `defineAtom(opCode, inputSchema, outputSchema, implementation, { cost, timeoutMs, docs, effects })`
 2. Add to `src/vm/atoms/` and export from `src/vm/atoms/index.ts`
 3. Add tests
 4. Run `bun run test:fast`
@@ -270,6 +276,7 @@ Coverage targets: 98% lines on `src/vm/runtime.ts` (security-critical), 80%+ ove
 - `cost` can be static number or dynamic: `(input, ctx) => number`
 - `timeoutMs` defaults to 1000ms; use `0` for no timeout (e.g., `seq`)
 - Atoms are always async; fuel deduction is automatic in the `exec` wrapper
+- `effects` defaults to `'pure'`; **set `'io'` for any atom that touches `ctx.capabilities` (fetch/store/llm/agent/code), is nondeterministic (random/uuid), or has side effects (console)**. This drives predicate-safety (a predicate may only call pure atoms — see `experiments/predicates/`). Core IO atoms are tagged centrally via `EFFECTFUL_CORE_OPS` in `runtime.ts`; the invariant is guarded by `src/vm/atom-effects.test.ts`.
 
 ### Debugging Agents
 
@@ -303,6 +310,7 @@ Full syntax documentation is in [`CLAUDE-TJS-SYNTAX.md`](CLAUDE-TJS-SYNTAX.md).
 - **Return types**: `function add(a: 0, b: 0): 0 { ... }` (colon syntax, same as TypeScript)
 - **Safety markers**: `!` = unsafe (skip validation), `?` = safe (explicit validation)
 - **Mode defaults**: Native TJS has all modes ON by default (`TjsEquals`, `TjsClass`, `TjsDate`, `TjsNoeval`, `TjsNoVar`, `TjsStandard`). TS-originated code (`fromTS`) and AJS/VM code get modes OFF. `TjsCompat` directive explicitly disables all modes. `TjsStrict` enables all modes (useful for TS-originated code opting in).
+- **Source dialect (`dialect: 'js' | 'tjs'`)**: the public, programmatic way to set the modes-on/off default. `tjs(src, { dialect: 'js' })` preserves plain-JS semantics (modes OFF, `safety: 'none'`); `'tjs'` (or a bare string) is native TJS (modes ON). `dialect` is authoritative; otherwise inferred from the `fromTS` annotation / `vmTarget`. For file-based tooling, use the canonical extension→dialect helpers `dialectForFilename(filename)` / `sourceKindForFilename(filename)` from `tjs-lang/lang` (`.js`/`.mjs`/`.cjs` → `'js'`, `.tjs` → `'tjs'`, `.ts` → use `fromTS`). This upholds the **TJS ⊇ JS** invariant — see `PRINCIPLES.md`. (`.tjs` is a _better_ language, not just JS; choosing it is the opt-in to the modes.)
 - **Bang access**: `x!.foo` — returns MonadicError if `x` is null/undefined, otherwise bare `x.foo`. Chains propagate: `x!.foo!.bar`.
 - **Type/Generic/FunctionPredicate**: Three declaration forms for runtime type predicates
 - **`const!`**: Compile-time immutability, zero runtime cost
@@ -478,6 +486,7 @@ The CLI (`bun src/cli/tjs.ts run`) does NOT inject the test-block `expect` harne
 
 ### Additional Documentation
 
+- `PRINCIPLES.md` — **non-negotiable language invariants**: options-off TJS ⊇ JS, and TJS ⊇ AJS. A richer layer may do _more_ with the same source but must never make subset-legal code _illegal_ (e.g. un-runnable signature tests are inconclusive, not errors). Read before changing parser/transpiler acceptance or signature-test behavior; a subset violation is a bug.
 - `llms.txt` — agent-facing navigation index (ships in npm bundle); points to docs and source entry points
 - `guides/footguns.md` — JS footguns TJS fixes (boxed-primitive truthiness, `==` coercion, `typeof null`, uninitialized `let`, etc.). Demo: `examples/js-footguns-fixed.tjs`.
 - `guides/playground-imports.md` — how the playground/dev-server resolves bare imports: TFS service worker, default JSDelivr `/+esm` routing, esm.sh allowlist for peer-dep packages (React), CDN hints (`jsdelivr/`, `esmsh/`, `unpkg/`, `github/`), and full-URL passthrough.

package/demo/autocomplete.test.ts

@@ -40,6 +40,43 @@ describe('getCompletions', () => {
     })
   })
 
+  describe('destructured bindings (scope-aware)', () => {
+    // Regression: the old regex `const NAME =` extractor missed all
+    // destructuring, so the tosijs todo example suggested nothing.
+    const todo = `import { elements, tosi } from 'tosijs'
+const { todoApp } = tosi({ todoApp: { items: [], newItem: '' } })
+const { h1, ul, template, li, label, input, button } = elements
+`
+
+    it('suggests destructured locals (todoApp, h1, button)', () => {
+      const completions = getCompletions({
+        source: todo,
+        position: todo.length,
+      })
+      const labels = completions.map((c) => c.label)
+      expect(labels).toContain('todoApp')
+      expect(labels).toContain('h1')
+      expect(labels).toContain('button')
+    })
+
+    it('shows where a destructured binding came from', () => {
+      const completions = getCompletions({
+        source: todo,
+        position: todo.length,
+      })
+      expect(completions.find((c) => c.label === 'h1')?.detail).toBe(
+        '∈ elements'
+      )
+    })
+
+    it('filters destructured locals by prefix', () => {
+      const src = todo + 'tod'
+      const completions = getCompletions({ source: src, position: src.length })
+      expect(completions.map((c) => c.label)).toContain('todoApp')
+      expect(completions.every((c) => c.label.startsWith('tod'))).toBe(true)
+    })
+  })
+
   describe('type completions', () => {
     it('should suggest types after colon', () => {
       const completions = getCompletions({