tjs-lang 0.8.1 → 0.8.3

package/src/lang/suggest.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'bun:test'
+import { suggest } from './predicate'
+
+const vals = (s: ReturnType<typeof suggest>) =>
+  s.filter((x) => x.kind === 'value').map((x) => x.value)
+const stubs = (s: ReturnType<typeof suggest>) =>
+  s.filter((x) => x.kind === 'stub').map((x) => x.value)
+
+describe('suggest — autocomplete from predicate clusters', () => {
+  // The keyword set is a plain array literal + an equality check; the open-ended
+  // values ride in `startsWith` guards. TS could enumerate the union but not the
+  // open-ended `var(--`; a TS `string` fallback offers neither.
+  const ANIMATION = String.raw`
+    var TIMING = ['linear','ease','ease-in','ease-out','ease-in-out']
+    function isTime(t){ return /^-?[0-9.]+m?s$/.test(t) }
+    function isIter(t){ return t == 'infinite' || /^[0-9.]+$/.test(t) }
+    function isVar(t){ return typeof t == 'string' && t.startsWith('var(--') }
+    function isTok(t){ return isTime(t) || isIter(t) || TIMING.includes(t) || isVar(t) }
+    function isAnimationToken(v){ return typeof v == 'string' && isTok(v.trim()) }
+  `
+
+  it('mines the keyword set (array literal + equality literal)', () => {
+    const v = vals(suggest(ANIMATION))
+    expect(v).toContain('linear')
+    expect(v).toContain('ease-in-out')
+    expect(v).toContain('infinite') // from `t == 'infinite'`
+  })
+
+  it('mines open-ended `startsWith` guards as stubs (TS string can offer none)', () => {
+    expect(stubs(suggest(ANIMATION))).toContain('var(--')
+  })
+
+  it('filters by the prefix typed so far', () => {
+    const v = vals(suggest(ANIMATION, { prefix: 'ease-' }))
+    expect(v).toEqual(['ease-in', 'ease-in-out', 'ease-out'])
+    expect(v).not.toContain('linear')
+  })
+
+  it('a stub matches when the user is mid-typing into it', () => {
+    // user has typed `var(`; the `var(--` stub is still the relevant completion
+    expect(stubs(suggest(ANIMATION, { prefix: 'var(' }))).toContain('var(--')
+    // and once they pass it, it still matches by startsWith
+    expect(stubs(suggest(ANIMATION, { prefix: 'var(--' }))).toContain('var(--')
+  })
+
+  it('validated suggestions are exactly what the predicate accepts', () => {
+    // `bad` is in the keyword array but the entry predicate excludes it — so the
+    // mined candidate is filtered out by running it through the predicate.
+    const src = String.raw`
+      var ALL = ['yes','maybe','bad']
+      function check(v){ return ALL.includes(v) && v != 'bad' }
+    `
+    const v = vals(suggest(src))
+    expect(v).toContain('yes')
+    expect(v).toContain('maybe')
+    expect(v).not.toContain('bad') // mined, but predicate rejects it
+  })
+
+  it('validate:false returns raw mined candidates (no predicate run)', () => {
+    const src = String.raw`
+      var ALL = ['yes','maybe','bad']
+      function check(v){ return ALL.includes(v) && v != 'bad' }
+    `
+    const v = vals(suggest(src, { validate: false }))
+    expect(v).toContain('yes')
+    expect(v).toContain('bad') // un-validated → the excluded literal leaks in
+  })
+
+  it('respects limit', () => {
+    expect(suggest(ANIMATION, { limit: 2 }).length).toBe(2)
+  })
+
+  it('values sort before stubs', () => {
+    const s = suggest(ANIMATION)
+    const firstStub = s.findIndex((x) => x.kind === 'stub')
+    const lastValue = s.map((x) => x.kind).lastIndexOf('value')
+    expect(lastValue).toBeLessThan(firstStub)
+  })
+
+  it('empty / unparseable source yields nothing', () => {
+    expect(suggest('')).toEqual([])
+    expect(suggest('function (')).toEqual([])
+  })
+})

package/src/lang/transpiler.ts

@@ -16,6 +16,40 @@ export { transpile, ajs, tjs, createAgent, getToolDefinitions } from './core'
 // Parser
 export { parse, preprocess, extractTDoc } from './parser'
 
+// Dialect resolution for file-based tooling (extension → dialect)
+export {
+  dialectForFilename,
+  sourceKindForFilename,
+  type Dialect,
+  type SourceKind,
+} from './dialect'
+
+// Predicate-safety: verify a cluster of pure, synchronous, composable predicates
+export {
+  verifyPredicate,
+  compilePredicate,
+  suggest,
+  effectfulFromAtoms,
+  formatPredicateDiagnostics,
+  PredicateFuelExhausted,
+  type PredicateDiagnostic,
+  type PredicateVerifyResult,
+  type VerifyPredicateOptions,
+  type CompilePredicateOptions,
+  type Suggestion,
+  type SuggestOptions,
+} from './predicate'
+
+// Predicate-aware JSON-Schema: the `$predicate` keyword (computational types)
+export {
+  compilePredicateSchema,
+  validatePredicateSchema,
+  type PredicateSchema,
+  type SchemaError,
+  type SchemaValidationResult,
+  type PredicateSchemaOptions,
+} from './predicate-schema'
+
 // AST emitter
 export { transformFunction } from './emitters/ast'
 

package/src/lang/types.ts

@@ -225,6 +225,21 @@ export interface TransformContext {
   filename: string
   /** Options */
   options: TranspileOptions
+  /**
+   * Helper functions (top-level functions declared before the entry function).
+   * Calls to these names emit `callLocal` instead of treating them as atom calls.
+   */
+  helpers?: Map<string, any /* FunctionDeclaration */>
+  /**
+   * Cache of transformed helper bodies. Lazily populated as helpers are
+   * referenced from the entry function (or from other helpers).
+   */
+  helperSteps?: Map<string, { steps: any[]; paramNames: string[] }>
+  /**
+   * Names of helpers currently being transformed. Used to detect direct or
+   * transitive recursion.
+   */
+  helperTransforming?: Set<string>
 }
 
 /** Create a child context for nested scopes */
@@ -239,6 +254,9 @@ export function createChildContext(parent: TransformContext): TransformContext {
     source: parent.source,
     filename: parent.filename,
     options: parent.options,
+    helpers: parent.helpers,
+    helperSteps: parent.helperSteps,
+    helperTransforming: parent.helperTransforming,
   }
 }
 

package/src/lang/wasm.test.ts

@@ -2317,14 +2317,20 @@ describe('boundary distribution form (Phase 4)', () => {
   async function dynamicImportLibrary(transpiled: string): Promise<any> {
     const { tmpdir } = await import('node:os')
     const { join } = await import('node:path')
-    const { writeFileSync, unlinkSync } = await import('node:fs')
+    const { writeFileSync, unlinkSync, realpathSync } = await import('node:fs')
+    const { pathToFileURL } = await import('node:url')
     const path = join(
       tmpdir(),
       `tjs-lib-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.mjs`
     )
     writeFileSync(path, transpiled)
+    // Resolve macOS /var → /private/var symlink and use file:// URL — bun's
+    // resolver in subsequent test cases (after a `new Function(emittedCode)`
+    // execution earlier in the same file) fails on bare absolute paths with
+    // "Cannot find module ... from ''". This form is robust to that state.
+    const url = pathToFileURL(realpathSync(path)).href
     try {
-      const mod = await import(path)
+      const mod = await import(url)
       // Wait for the async wasm bootstrap inside the module to finish.
       // The bootstrap runs as a top-level IIFE; instantiation is async.
       await new Promise((r) => setTimeout(r, 100))

package/src/linalg/linalg.test.ts

@@ -14,9 +14,10 @@
  */
 
 import { describe, it, expect } from 'bun:test'
-import { readFileSync } from 'node:fs'
+import { readFileSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
+import { pathToFileURL } from 'node:url'
 import { writeFileSync, unlinkSync } from 'node:fs'
 
 const LINALG_PATH = join(import.meta.dir, 'index.tjs')
@@ -41,8 +42,13 @@ async function dynamicImportLibrary(transpiled: string): Promise<any> {
     `linalg-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.mjs`
   )
   writeFileSync(path, transpiled)
+  // Resolve macOS /var → /private/var symlink and use file:// URL — bun's
+  // resolver in subsequent test cases (after a `new Function(emittedCode)`
+  // execution earlier in the same file) fails on bare absolute paths with
+  // "Cannot find module ... from ''". This form is robust to that state.
+  const url = pathToFileURL(realpathSync(path)).href
   try {
-    const mod = await import(path)
+    const mod = await import(url)
     // Wait for the async wasm bootstrap inside the module to finish
     await new Promise((r) => setTimeout(r, 100))
     return mod

package/src/use-cases/batteries.test.ts

@@ -252,4 +252,8 @@ describe('Batteries Included', () => {
     expect(msg.tool_calls[0].function.name).toBe('get_weather')
     expect(msg.tool_calls[0].function.arguments).toBe('{"city":"Paris"}')
   })
+
+  it('LLM battery atoms have IO-friendly timeouts', () => {
+    expect(llmPredictBattery.timeoutMs).toBeGreaterThanOrEqual(60000)
+  })
 })

package/src/use-cases/local-helpers.test.ts

@@ -0,0 +1,219 @@
+import { describe, it, expect } from 'bun:test'
+import { ajs } from '../transpiler'
+import { transpile } from '../lang'
+import { AgentVM } from '../vm'
+
+/**
+ * Local helper functions: an agent source file may declare multiple top-level
+ * functions. The LAST is the entry point; the preceding ones are helpers,
+ * invoked via the `callLocal` atom. Helpers are top-level siblings — isolated
+ * scopes that see only their parameters, like ordinary functions.
+ */
+describe('Local helper functions', () => {
+  const VM = new AgentVM()
+  const run = async (src: string, args: Record<string, any>) =>
+    (await VM.run(ajs(src), args)).result
+
+  it('invokes a scalar-returning helper from the entry function', async () => {
+    const result = await run(
+      `
+      function double(x) { return x * 2 }
+      function main(n) {
+        const d = double(n)
+        return { d }
+      }`,
+      { n: 5 }
+    )
+    expect(result.d).toBe(10)
+  })
+
+  it('lets a helper call another helper', async () => {
+    const result = await run(
+      `
+      function double(x) { return x * 2 }
+      function addOne(x) {
+        const d = double(x)
+        return d + 1
+      }
+      function main(n) {
+        const a = double(n)
+        const b = addOne(n)
+        return { a, b }
+      }`,
+      { n: 5 }
+    )
+    expect(result).toEqual({ a: 10, b: 11 })
+  })
+
+  it('allows helpers to return arrays and objects', async () => {
+    const result = await run(
+      `
+      function pair(x) { return [x, x] }
+      function wrap(x) { return { value: x } }
+      function main(n) {
+        const p = pair(n)
+        const w = wrap(n)
+        return { p, w }
+      }`,
+      { n: 3 }
+    )
+    expect(result).toEqual({ p: [3, 3], w: { value: 3 } })
+  })
+
+  it('supports idiomatic TJS typed/example params (colon shorthand)', async () => {
+    // Examples are representative values: floats for a fractional-scaling fn.
+    const result = await run(
+      `
+      function scale(x: 1.5, factor: 0.5): 0.75 { return x * factor }
+      function main(n: 1.5): 0.75 {
+        const s = scale(n, 0.5)
+        return { s }
+      }`,
+      { n: 3 }
+    )
+    expect(result.s).toBe(1.5)
+  })
+
+  it('supports multiple parameters', async () => {
+    const result = await run(
+      `
+      function add(a, b) { return a + b }
+      function main(x, y) {
+        const sum = add(x, y)
+        return { sum }
+      }`,
+      { x: 7, y: 8 }
+    )
+    expect(result.sum).toBe(15)
+  })
+
+  it('isolates helper scope — helpers cannot see the caller locals', async () => {
+    // `secret` is a local in main (= 42). The helper references a bare
+    // `secret`; under isolation it is NOT in scope, so AJS falls back to the
+    // bare-string literal "secret". A scope leak would instead expose main's
+    // 42 — so the guarantee is simply: the helper never sees the caller value.
+    const result = await run(
+      `
+      function leak(x) { return { x, secret } }
+      function main(n) {
+        const secret = 42
+        const r = leak(n)
+        return r
+      }`,
+      { n: 1 }
+    )
+    expect(result.x).toBe(1)
+    expect(result.secret).not.toBe(42) // no leak of caller's local
+    expect(result.secret).toBe('secret') // AJS bare-string fallback
+  })
+
+  it('does not let helper return exit the caller agent', async () => {
+    // The helper returns, then main keeps running and returns its own object.
+    const result = await run(
+      `
+      function step(x) { return x + 100 }
+      function main(n) {
+        const a = step(n)
+        const b = step(a)
+        return { a, b }
+      }`,
+      { n: 1 }
+    )
+    expect(result).toEqual({ a: 101, b: 201 })
+  })
+
+  // --- transpile-time guards -------------------------------------------------
+
+  const expectTranspileError = (src: string, match: RegExp) =>
+    expect(() => transpile(src, { vmTarget: true })).toThrow(match)
+
+  it('rejects helper calls nested inside expressions', () => {
+    expectTranspileError(
+      `
+      function double(x) { return x * 2 }
+      function main(n) { return { v: double(n) + 1 } }`,
+      /cannot be called inside an expression/
+    )
+  })
+
+  it('supports recursion (bounded by fuel/timeout, not rejected)', async () => {
+    // Recursive factorial — by-reference dispatch makes this a runtime loop.
+    const result = await run(
+      `
+      function fact(n) {
+        if (n <= 1) { return 1 }
+        const prev = fact(n - 1)
+        return n * prev
+      }
+      function main(n) {
+        const f = fact(n)
+        return { f }
+      }`,
+      { n: 5 }
+    )
+    expect(result.f).toBe(120)
+  })
+
+  it('supports mutual recursion', async () => {
+    const result = await run(
+      `
+      function isEven(n) {
+        if (n == 0) { return true }
+        const r = isOdd(n - 1)
+        return r
+      }
+      function isOdd(n) {
+        if (n == 0) { return false }
+        const r = isEven(n - 1)
+        return r
+      }
+      function main(n) {
+        const even = isEven(n)
+        return { even }
+      }`,
+      { n: 10 }
+    )
+    expect(result.even).toBe(true)
+  })
+
+  it('turns runaway recursion into a clean error, not a host crash', async () => {
+    // Unbounded recursion: must surface as a monadic error (depth cap or fuel),
+    // never a thrown RangeError that crashes the host VM.
+    const out = await VM.run(
+      ajs(`
+      function loop(n) { const r = loop(n); return r }
+      function main(n) { const v = loop(n); return { v } }`),
+      { n: 1 },
+      { fuel: 100000 }
+    )
+    expect(out.error).toBeDefined()
+    expect(out.error?.message).toMatch(/depth|fuel/i)
+  })
+
+  it('rejects arity mismatches', () => {
+    expectTranspileError(
+      `
+      function add(a, b) { return a + b }
+      function main(n) { const v = add(n); return { v } }`,
+      /expects 2 argument\(s\), got 1/
+    )
+  })
+
+  it('rejects same-name same-arity functions (collision)', () => {
+    // Two identical-signature `dup` declarations collide. The polymorphic-merge
+    // pass (which runs during parse, before helper extraction) catches this
+    // first — either way it's a clear, deterministic rejection.
+    expectTranspileError(
+      `
+      function dup(x) { return x }
+      function dup(x) { return x }
+      function main(n) { const v = dup(n); return { v } }`,
+      /ambiguous signatures|Duplicate helper/
+    )
+  })
+
+  it('still transpiles a single-function agent (no helpers)', async () => {
+    const result = await run(`function main(n) { return { n } }`, { n: 9 })
+    expect(result.n).toBe(9)
+  })
+})

package/src/use-cases/timeout-overrides.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect } from 'vitest'
+import { AgentVM, isAgentError, defineAtom } from '../index'
+import { s } from 'tosijs-schema'
+
+// A deliberately slow atom whose builtin timeout would normally trip.
+const slowAtom = defineAtom(
+  'slow',
+  s.object({ ms: s.number }),
+  undefined,
+  async ({ ms }) => {
+    await new Promise((resolve) => setTimeout(resolve, ms))
+  },
+  { docs: 'Slow IO atom for testing', cost: 0.01, timeoutMs: 100 }
+)
+
+describe('Per-atom Timeout Overrides', () => {
+  it('uses the atom default when no override is provided', async () => {
+    const vm = new AgentVM({ slow: slowAtom })
+
+    const ast = vm.Agent.step({ op: 'slow', ms: 200 }).toJSON()
+
+    const result = await vm.run(ast, {}, { fuel: 100 })
+
+    expect(result.error).toBeDefined()
+    expect(result.error?.message).toContain("Atom 'slow' timed out")
+  })
+
+  it('static override raises an atom timeout above its default', async () => {
+    const vm = new AgentVM({ slow: slowAtom })
+
+    const ast = vm.Agent.step({ op: 'slow', ms: 200 }).toJSON()
+
+    const result = await vm.run(
+      ast,
+      {},
+      {
+        fuel: 100,
+        timeoutOverrides: { slow: 5000 }, // raise from 100 → 5s
+      }
+    )
+
+    expect(result.error).toBeUndefined()
+  })
+
+  it('static override lowers an atom timeout below its default', async () => {
+    const vm = new AgentVM({ slow: slowAtom })
+
+    const ast = vm.Agent.step({ op: 'slow', ms: 100 }).toJSON()
+
+    const result = await vm.run(
+      ast,
+      {},
+      {
+        fuel: 100,
+        timeoutOverrides: { slow: 10 }, // lower from 100ms → 10ms
+      }
+    )
+
+    expect(result.error).toBeDefined()
+    expect(result.error?.message).toContain("Atom 'slow' timed out")
+  })
+
+  it('dynamic override receives input and ctx', async () => {
+    const vm = new AgentVM({ slow: slowAtom })
+
+    const ast = vm.Agent.step({ op: 'slow', ms: 200 }).toJSON()
+
+    const result = await vm.run(
+      ast,
+      {},
+      {
+        fuel: 100,
+        timeoutOverrides: {
+          // Allow 10x the requested delay
+          slow: (input: any) => input.ms * 10,
+        },
+      }
+    )
+
+    expect(result.error).toBeUndefined()
+  })
+
+  it('override of 0 disables the per-atom timeout', async () => {
+    const vm = new AgentVM({ slow: slowAtom })
+
+    // ms > atom default (100), would normally trip
+    const ast = vm.Agent.step({ op: 'slow', ms: 300 }).toJSON()
+
+    const result = await vm.run(
+      ast,
+      {},
+      {
+        fuel: 100,
+        timeoutOverrides: { slow: 0 },
+      }
+    )
+
+    expect(result.error).toBeUndefined()
+  })
+
+  it('atom timeout still fires when no override matches that op', async () => {
+    const vm = new AgentVM({ slow: slowAtom })
+
+    const ast = vm.Agent.step({ op: 'slow', ms: 200 }).toJSON()
+
+    const result = await vm.run(
+      ast,
+      {},
+      {
+        fuel: 100,
+        timeoutOverrides: { somethingElse: 5000 },
+      }
+    )
+
+    expect(result.error).toBeDefined()
+    expect(isAgentError(result.error)).toBe(true)
+  })
+})
+
+describe('Default vm.run timeout', () => {
+  it('does not derive run timeout from fuel (formula removed)', async () => {
+    // Under the old `fuel * 10ms` formula, fuel=1 would timeout in 10ms —
+    // far less than the IO needed below. Under the atom-derived default
+    // (slowest atom × 2), a 200ms IO atom completes fine with tiny fuel.
+    const vm = new AgentVM({ slow: slowAtom })
+
+    const ast = vm.Agent.step({ op: 'slow', ms: 200 }).toJSON()
+
+    const result = await vm.run(
+      ast,
+      {},
+      {
+        fuel: 1000, // headroom for cost; the run-level timeout is what matters
+        timeoutOverrides: { slow: 0 }, // disable per-atom timeout
+        // no timeoutMs option — use the default
+      }
+    )
+
+    expect(result.error).toBeUndefined()
+  })
+
+  it('derives the default from the slowest atom × 2 (never below the slowest atom budget)', () => {
+    // coreAtoms include 120s atoms (llm/runCode); the run-level default must
+    // cover them, else those per-atom budgets are dead config.
+    const core = new AgentVM()
+    expect(core.defaultRunTimeout).toBe(240_000) // 120s × 2
+
+    // A slower custom atom raises the default (self-adjusting).
+    const slow = defineAtom('slow5m', s.object({}), undefined, async () => {}, {
+      timeoutMs: 300_000,
+    })
+    const vm = new AgentVM({ slow5m: slow })
+    expect(vm.defaultRunTimeout).toBe(600_000) // 300s × 2
+    // and it always covers the slowest atom's own budget
+    expect(vm.defaultRunTimeout).toBeGreaterThanOrEqual(300_000)
+  })
+
+  it('floors the default at 60s for a VM whose atoms are all fast', () => {
+    // `seq` etc. have timeoutMs: 0 (no timeout) and are excluded; if the only
+    // finite budgets were tiny, the floor keeps a sane backstop.
+    const fast = defineAtom('fast', s.object({}), undefined, async () => {}, {
+      timeoutMs: 50,
+    })
+    const vm = new AgentVM({ fast })
+    // coreAtoms still contribute their 120s atoms, so this VM is 240s; the floor
+    // is exercised conceptually — assert it's at least the 60s minimum.
+    expect(vm.defaultRunTimeout).toBeGreaterThanOrEqual(60_000)
+  })
+})

package/src/vm/atom-effects.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'bun:test'
+import { coreAtoms, EFFECTFUL_CORE_OPS, type AtomDef } from './runtime'
+import { batteryAtoms } from './atoms/index'
+
+const allAtoms = { ...coreAtoms, ...batteryAtoms } as Record<string, AtomDef>
+
+describe('atom effects classification (predicate-safety keystone)', () => {
+  it('every atom is classified pure | io', () => {
+    for (const [op, atom] of Object.entries(allAtoms)) {
+      expect(atom.effects, `${op} has no effects tag`).toMatch(/^(pure|io)$/)
+    }
+  })
+
+  it('the declared effectful core ops are all tagged io', () => {
+    for (const op of EFFECTFUL_CORE_OPS) {
+      expect(coreAtoms[op as keyof typeof coreAtoms]?.effects, op).toBe('io')
+    }
+  })
+
+  it('every battery atom is io (network calls)', () => {
+    for (const atom of Object.values(batteryAtoms) as AtomDef[]) {
+      expect(atom.effects, atom.op).toBe('io')
+    }
+  })
+
+  it('the pure substrate a predicate relies on is tagged pure', () => {
+    // data / control-flow atoms predicates compose from
+    const pure = [
+      'map',
+      'filter',
+      'reduce',
+      'find',
+      'len',
+      'split',
+      'join',
+      'keys',
+      'pick',
+      'omit',
+      'merge',
+      'regexMatch',
+      'jsonParse',
+      'callLocal',
+      'if',
+      'while',
+      'return',
+      'scope',
+    ]
+    for (const op of pure) {
+      expect(coreAtoms[op as keyof typeof coreAtoms]?.effects, op).toBe('pure')
+    }
+  })
+
+  it('the IO atoms are exactly the ones that may not appear in a predicate', () => {
+    const io = Object.values(allAtoms)
+      .filter((a) => a.effects === 'io')
+      .map((a) => a.op)
+    // sanity: the capability-touching atoms are all present
+    expect(io).toEqual(
+      expect.arrayContaining([
+        'httpFetch',
+        'storeGet',
+        'llmPredict',
+        'agentRun',
+        'runCode',
+        'llmVision',
+      ])
+    )
+    // and none of the pure data ops leaked in
+    expect(io).not.toContain('map')
+    expect(io).not.toContain('jsonParse')
+  })
+})