tjs-lang 0.8.2 → 0.8.4

package/src/lang/transpiler.ts

@@ -24,6 +24,32 @@ export {
   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/runtime.test.ts

@@ -596,8 +596,8 @@ describe('Edge Cases', () => {
     expect(result.result.res).toEqual({ value: 42 })
   })
 
-  describe('structural equality in expressions', () => {
-    it('== compares arrays structurally', async () => {
+  describe('footgun-free equality in expressions (== is NOT structural)', () => {
+    it('distinct arrays are NOT equal (== matches TJS, not structural)', async () => {
       const ast = {
         op: 'seq',
         steps: [
@@ -621,10 +621,10 @@ describe('Edge Cases', () => {
         ],
       } as any
       const result = await vm.run(ast, {})
-      expect(result.result.res).toBe(true)
+      expect(result.result.res).toBe(false) // distinct arrays — NOT structural
     })
 
-    it('== compares objects structurally', async () => {
+    it('distinct objects are NOT equal (== matches TJS, not structural)', async () => {
       const ast = {
         op: 'seq',
         steps: [
@@ -648,7 +648,7 @@ describe('Edge Cases', () => {
         ],
       } as any
       const result = await vm.run(ast, {})
-      expect(result.result.res).toBe(true)
+      expect(result.result.res).toBe(false) // distinct objects — NOT structural
     })
 
     it('== does not coerce types', async () => {
@@ -678,7 +678,7 @@ describe('Edge Cases', () => {
       expect(result.result.res).toBe(false) // no coercion
     })
 
-    it('!= returns true for structurally different objects', async () => {
+    it('!= returns true for distinct objects', async () => {
       const ast = {
         op: 'seq',
         steps: [

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')
+  })
+})

package/src/vm/atoms/batteries.ts

@@ -229,3 +229,15 @@ export const llmVision = defineAtom(
   },
   { docs: 'Analyze images using a vision model', timeoutMs: 120000, cost: 150 }
 )
+
+// Every battery atom is IO (embedding/LLM/vector-store network calls).
+for (const atom of [
+  storeVectorize,
+  storeCreateCollection,
+  storeVectorAdd,
+  storeSearch,
+  llmPredictBattery,
+  llmVision,
+]) {
+  atom.effects = 'io'
+}

package/src/vm/equality.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'bun:test'
+import { evaluateExpr } from './runtime'
+
+/**
+ * AJS `==`/`!=` must match TJS `==` (Eq): footgun-free `===`, NOT structural.
+ * This used to do deep structural comparison in the VM — an early, unconsidered
+ * divergence from TJS `==` (so `[1,2] == [1,2]` was `true` in AJS but `false` in
+ * TJS). Now consistent: distinct objects/arrays are distinct; structural
+ * equality is an explicit operation, never `==`.
+ */
+const lit = (value: unknown) => ({ $expr: 'literal' as const, value })
+const evalEq = (op: '==' | '!=', a: unknown, b: unknown) =>
+  evaluateExpr(
+    { $expr: 'binary', op, left: lit(a), right: lit(b) } as any,
+    { state: {}, args: {} } as any
+  )
+
+describe('AJS == / != — footgun-free, NOT structural (consistent with TJS)', () => {
+  it('distinct arrays/objects are NOT equal (the divergence fix)', () => {
+    expect(evalEq('==', [1, 2], [1, 2])).toBe(false)
+    expect(evalEq('==', { a: 1 }, { a: 1 })).toBe(false)
+    expect(evalEq('!=', [1, 2], [1, 2])).toBe(true)
+  })
+
+  it('identity still holds for the same reference', () => {
+    const shared = { a: 1 }
+    expect(evalEq('==', shared, shared)).toBe(true)
+    const arr = [1, 2]
+    expect(evalEq('==', arr, arr)).toBe(true)
+  })
+
+  it('no type coercion', () => {
+    expect(evalEq('==', '5', 5)).toBe(false)
+    expect(evalEq('==', '', false)).toBe(false)
+    expect(evalEq('==', 0, false)).toBe(false)
+  })
+
+  it('unwraps boxed primitives', () => {
+    expect(evalEq('==', new Boolean(false) as any, false)).toBe(true)
+    expect(evalEq('==', new Number(5) as any, 5)).toBe(true)
+  })
+
+  it('null/undefined equal; NaN equal to itself', () => {
+    expect(evalEq('==', null, undefined)).toBe(true)
+    expect(evalEq('==', NaN, NaN)).toBe(true)
+    expect(evalEq('==', null, 0)).toBe(false)
+  })
+
+  it('scalars compare as expected', () => {
+    expect(evalEq('==', 1, 1)).toBe(true)
+    expect(evalEq('==', 'x', 'x')).toBe(true)
+    expect(evalEq('!=', 1, 2)).toBe(true)
+  })
+
+  it('=== / !== remain strict identity (unchanged)', () => {
+    expect(evalEq('===' as any, [1], [1])).toBe(false)
+    expect(evalEq('===' as any, 5, 5)).toBe(true)
+  })
+})

package/src/vm/runtime.ts

@@ -1,69 +1,36 @@
 import { s, validate, filter as schemaFilter } from 'tosijs-schema'
 
-/** Well-known symbol for custom equality (matches src/lang/runtime.ts) */
-const tjsEquals = Symbol.for('tjs.equals')
-
 /**
- * Structural equality for AJS expressions.
- * Mirrors the TJS Is() function: symbol → .Equals → structural.
+ * AJS `==`/`!=` equality — **footgun-free `===`**, consistent with TJS `Eq`
+ * (`src/lang/runtime.ts`). NOT structural: it unwraps boxed primitives, treats
+ * `null`/`undefined` as equal and `NaN` as equal to itself, but does NOT coerce
+ * across types, and distinct objects/arrays are distinct (`[1,2] != [1,2]`).
+ *
+ * (Originally the VM did deep structural comparison here — an early, unconsidered
+ * divergence from TJS `==`. It was also a SECURITY hole: a single `==` node costs
+ * a flat EXPR_FUEL_COST, but the structural walk charged nothing per element, so
+ * `==` on an attacker-controlled large structure was an unbounded-work / fuel-
+ * bypass DoS — exactly what AJS exists to prevent. `eqValue` is O(1).
+ *
+ * Structural equality is an explicit operation: in TJS it's the `Is`/`IsNot`
+ * function; AJS can grow an `Is` atom if/when needed — but it MUST be fuel-metered
+ * per element compared, or it reintroduces the same DoS.)
  */
-function isStructurallyEqual(a: unknown, b: unknown): boolean {
-  // Symbol protocol
-  if (
-    a !== null &&
-    typeof a === 'object' &&
-    typeof (a as any)[tjsEquals] === 'function'
-  ) {
-    return (a as any)[tjsEquals](b)
+function eqValue(a: unknown, b: unknown): boolean {
+  if (a instanceof String || a instanceof Number || a instanceof Boolean) {
+    a = a.valueOf()
   }
-  if (
-    b !== null &&
-    typeof b === 'object' &&
-    typeof (b as any)[tjsEquals] === 'function'
-  ) {
-    return (b as any)[tjsEquals](a)
+  if (b instanceof String || b instanceof Number || b instanceof Boolean) {
+    b = b.valueOf()
   }
-
-  // .Equals method
-  if (
-    a !== null &&
-    typeof a === 'object' &&
-    typeof (a as any).Equals === 'function'
-  ) {
-    return (a as any).Equals(b)
-  }
-  if (
-    b !== null &&
-    typeof b === 'object' &&
-    typeof (b as any).Equals === 'function'
-  ) {
-    return (b as any).Equals(a)
-  }
-
   if (a === b) return true
-
-  // Nullish equality (null == undefined)
-  if ((a === null || a === undefined) && (b === null || b === undefined))
+  if (typeof a === 'number' && typeof b === 'number' && isNaN(a) && isNaN(b)) {
     return true
-
-  if (a === null || a === undefined || b === null || b === undefined)
-    return false
-
-  if (typeof a !== typeof b) return false
-  if (typeof a !== 'object') return false
-
-  // Arrays
-  if (Array.isArray(a) && Array.isArray(b)) {
-    if (a.length !== b.length) return false
-    return a.every((v, i) => isStructurallyEqual(v, b[i]))
   }
-  if (Array.isArray(a) !== Array.isArray(b)) return false
-
-  // Objects
-  const keysA = Object.keys(a as object)
-  const keysB = Object.keys(b as object)
-  if (keysA.length !== keysB.length) return false
-  return keysA.every((k) => isStructurallyEqual((a as any)[k], (b as any)[k]))
+  if ((a === null || a === undefined) && (b === null || b === undefined)) {
+    return true
+  }
+  return false
 }
 
 // --- Monadic Error Type ---
@@ -180,6 +147,18 @@ export interface RuntimeContext {
 
 export type AtomExec = (step: any, ctx: RuntimeContext) => Promise<void>
 
+/**
+ * Effect classification of an atom.
+ * - `'pure'`: deterministic, no IO, no capability access, no observable side
+ *   effects — safe inside a synchronous predicate (see the predicate verifier).
+ * - `'io'`: touches `ctx.capabilities` (fetch/store/llm/agent/code), or is
+ *   nondeterministic (random/uuid), or has side effects (console). Not allowed
+ *   in a predicate.
+ * Defaults to `'pure'`; effectful atoms must opt into `'io'`. The invariant
+ * "anything touching ctx.capabilities is tagged 'io'" is guarded by a test.
+ */
+export type AtomEffects = 'pure' | 'io'
+
 export interface AtomDef {
   op: OpCode
   inputSchema: any
@@ -188,6 +167,7 @@ export interface AtomDef {
   docs?: string
   timeoutMs?: number
   cost?: number | ((input: any, ctx: RuntimeContext) => number)
+  effects?: AtomEffects
 }
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -199,6 +179,8 @@ export interface AtomOptions {
   docs?: string
   timeoutMs?: number
   cost?: number | ((input: any, ctx: RuntimeContext) => number)
+  /** Effect class — defaults to `'pure'`; effectful atoms set `'io'`. */
+  effects?: AtomEffects
 }
 
 export interface RunResult {
@@ -1189,9 +1171,9 @@ export function evaluateExpr(node: ExprNode, ctx: RuntimeContext): any {
         case '<=':
           return left <= right
         case '==':
-          return isStructurallyEqual(left, right)
+          return eqValue(left, right)
         case '!=':
-          return !isStructurallyEqual(left, right)
+          return !eqValue(left, right)
         case '===':
           return left === right
         case '!==':
@@ -1347,6 +1329,7 @@ export function defineAtom<I extends Record<string, any>, O = any>(
     docs = '',
     timeoutMs = 1000,
     cost = 1,
+    effects = 'pure',
   } = typeof options === 'string' ? { docs: options } : options
 
   const exec: AtomExec = async (step: any, ctx: RuntimeContext) => {
@@ -1446,6 +1429,7 @@ export function defineAtom<I extends Record<string, any>, O = any>(
     docs,
     timeoutMs,
     cost,
+    effects,
     create: (input: I) => ({ op, ...input }),
   }
 }
@@ -3114,3 +3098,37 @@ export const coreAtoms = {
   releaseProcedure,
   clearExpiredProcedures,
 }
+
+/**
+ * Effectful core atoms — anything that touches `ctx.capabilities`
+ * (fetch/store/llm/agent/code), is nondeterministic (random/uuid), or has
+ * observable side effects (console). Tagged centrally so the list reads as one
+ * audit surface; a test asserts every capability-touching atom is in here.
+ * Everything else defaults to `effects: 'pure'`.
+ */
+export const EFFECTFUL_CORE_OPS = [
+  'httpFetch',
+  'storeGet',
+  'storeSet',
+  'storeQuery',
+  'storeVectorSearch',
+  'llmPredict',
+  'agentRun',
+  'transpileCode',
+  'runCode',
+  'random',
+  'uuid',
+  'consoleLog',
+  'consoleWarn',
+  'consoleError',
+  'storeProcedure',
+  'releaseProcedure',
+  'clearExpiredProcedures',
+  'cache',
+  'memoize',
+] as const
+
+for (const op of EFFECTFUL_CORE_OPS) {
+  const atom = (coreAtoms as Record<string, AtomDef>)[op]
+  if (atom) atom.effects = 'io'
+}