tjs-lang 0.8.2 → 0.8.4

package/dist/src/lang/index.d.ts

@@ -25,6 +25,8 @@ import type { TranspileOptions, TranspileResult, FunctionSignature } from './typ
 export * from './types';
 export { parse, preprocess, extractTDoc, validateSingleFunction, extractFunctions, } from './parser';
 export { dialectForFilename, sourceKindForFilename, type Dialect, type SourceKind, } from './dialect';
+export { verifyPredicate, compilePredicate, suggest, effectfulFromAtoms, formatPredicateDiagnostics, PredicateFuelExhausted, type PredicateDiagnostic, type PredicateVerifyResult, type VerifyPredicateOptions, type CompilePredicateOptions, type Suggestion, type SuggestOptions, } from './predicate';
+export { compilePredicateSchema, validatePredicateSchema, type PredicateSchema, type SchemaError, type SchemaValidationResult, type PredicateSchemaOptions, } from './predicate-schema';
 export { transformFunction } from './emitters/ast';
 export { transpileToJS, stripModuleSyntax, stripTjsPreamble, type TJSTranspileOptions, type TJSTranspileResult, type TJSTypeInfo, } from './emitters/js';
 export { generateDTS, typeDescriptorToTS, type GenerateDTSOptions, } from './emitters/dts';

package/dist/src/lang/predicate-schema.d.ts

@@ -0,0 +1,39 @@
+import type { CompilePredicateOptions } from './predicate';
+/** A JSON-Schema node, optionally carrying a `$predicate` (predicate source). */
+export interface PredicateSchema {
+    type?: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+    properties?: Record<string, PredicateSchema>;
+    required?: string[];
+    items?: PredicateSchema;
+    /**
+     * Predicate cluster source. The LAST top-level function is the entry; it
+     * receives the value at this node and returns a boolean. Ignored by naive
+     * validators (it's a custom keyword); run by predicate-aware ones.
+     */
+    $predicate?: string;
+    [k: string]: unknown;
+}
+export interface SchemaError {
+    /** JSON-pointer-ish path to the offending value, e.g. `/style/color`. */
+    path: string;
+    message: string;
+}
+export interface SchemaValidationResult {
+    valid: boolean;
+    errors: SchemaError[];
+}
+export interface PredicateSchemaOptions extends CompilePredicateOptions {
+    /**
+     * Validate structure only — skip every `$predicate` (i.e. behave like a naive
+     * JSON-Schema validator). Useful for demonstrating progressive enhancement.
+     */
+    ignorePredicates?: boolean;
+}
+/**
+ * Compile a predicate-aware JSON-Schema into a reusable validator. Every
+ * `$predicate` cluster is verified + compiled once (fuel-bounded, IO-rejected);
+ * an invalid/unsafe predicate throws here, at compile time.
+ */
+export declare function compilePredicateSchema(schema: PredicateSchema, opts?: PredicateSchemaOptions): (value: unknown) => SchemaValidationResult;
+/** One-shot convenience: compile + validate. */
+export declare function validatePredicateSchema(schema: PredicateSchema, value: unknown, opts?: PredicateSchemaOptions): SchemaValidationResult;

package/dist/src/lang/predicate.d.ts

@@ -0,0 +1,103 @@
+export interface PredicateDiagnostic {
+    /** Name of the predicate the problem is in. */
+    predicate: string;
+    message: string;
+    line: number;
+    column: number;
+}
+export interface PredicateVerifyResult {
+    safe: boolean;
+    /** Names of the top-level functions found (the predicate cluster). */
+    predicates: string[];
+    diagnostics: PredicateDiagnostic[];
+}
+export interface VerifyPredicateOptions {
+    /**
+     * Names that are effectful and must not be called — IO atoms + JS IO globals.
+     * Compose from the atom registry with `effectfulFromAtoms`. The built-in JS IO
+     * globals are always included.
+     */
+    effectful?: Set<string>;
+    /**
+     * Externally-verified predicate names this source may compose with (a shared
+     * registry), in addition to the functions declared in `source`.
+     */
+    knownPredicates?: Set<string>;
+}
+/**
+ * Build the effectful-name set from a VM atom registry: every atom tagged
+ * `effects: 'io'`, plus the built-in JS IO globals. This is how the verifier
+ * consumes the atom-effects classification (the keystone).
+ */
+export declare function effectfulFromAtoms(atoms: Record<string, {
+    op?: string;
+    effects?: 'pure' | 'io';
+}>): Set<string>;
+/**
+ * Verify every top-level function declaration in `source` is predicate-safe.
+ * Returns all diagnostics; `safe` is true iff there are none (closure property).
+ */
+export declare function verifyPredicate(source: string, opts?: VerifyPredicateOptions): PredicateVerifyResult;
+/** Format diagnostics for a thrown error / log. */
+export declare function formatPredicateDiagnostics(d: PredicateDiagnostic[]): string;
+export interface Suggestion {
+    value: string;
+    /**
+     * `'value'` — a concrete candidate (a keyword/literal the predicate accepts);
+     * `'stub'`  — a partial completion to keep typing (e.g. `var(--`, `calc(`),
+     *             mined from a `startsWith(...)` guard. TS's `string` fallback
+     *             offers neither; a finite TS union offers only `'value'`.
+     */
+    kind: 'value' | 'stub';
+}
+export interface SuggestOptions extends CompilePredicateOptions {
+    /** Only return candidates relevant to the text typed so far. */
+    prefix?: string;
+    /** Cap the number of suggestions (default 50). */
+    limit?: number;
+    /**
+     * Run each mined *value* through the compiled entry predicate and keep only
+     * those that actually pass — so completions are guaranteed valid, not merely
+     * enumerated. Default true when the cluster is predicate-safe; stubs are never
+     * validated (they're partial by construction).
+     */
+    validate?: boolean;
+    /** Entry predicate to validate against (default: last top-level function). */
+    entry?: string;
+}
+/**
+ * Mine a predicate cluster's source for autocomplete candidates. Two sources:
+ *   - **values** — string literals compared with `==`/`===` and members of
+ *     array literals (the keyword sets a predicate checks membership against).
+ *   - **stubs** — the argument of a `.startsWith(...)` guard, surfaced as a
+ *     partial completion (`var(--`, `calc(`) the user keeps typing.
+ *
+ * Pure syntactic mining over the parsed source — no execution. By default the
+ * mined *values* are then run through the compiled entry predicate, so the
+ * returned set is exactly what the predicate accepts (a literal that only ever
+ * appears in a `!=` / negative context is dropped). This is the autocomplete
+ * win over a TS `string` fallback (which suggests nothing) and over a finite TS
+ * union (which can't offer the open-ended `var(--`/`calc(` stubs).
+ */
+export declare function suggest(source: string, opts?: SuggestOptions): Suggestion[];
+/** Thrown when a predicate exceeds its fuel budget (likely a pathological input). */
+export declare class PredicateFuelExhausted extends Error {
+    constructor(budget: number);
+}
+export interface CompilePredicateOptions extends VerifyPredicateOptions {
+    /** Max fuel per top-level predicate call (default 1,000,000). */
+    fuel?: number;
+}
+/**
+ * Verify, then compile the cluster to native synchronous JS functions —
+ * **fuel-bounded and global-shadowed**. Throws (with located diagnostics) at
+ * definition time if not predicate-safe.
+ *
+ * Each compiled predicate runs with a fresh fuel budget; a runaway input throws
+ * `PredicateFuelExhausted` rather than hanging. The effectful globals are
+ * shadowed to `undefined` as defense-in-depth beneath the static verifier.
+ *
+ * NOTE: preserves JS semantics (no structural-`==` rewrite yet — a future
+ * opt-in). Emission is offset-spliced source, not a full AJS-AST→JS codegen.
+ */
+export declare function compilePredicate(source: string, exportNames: string[], opts?: CompilePredicateOptions): Record<string, (...args: any[]) => any>;

package/dist/src/lang/transpiler.d.ts

@@ -12,6 +12,8 @@
 export { transpile, ajs, tjs, createAgent, getToolDefinitions } from './core';
 export { parse, preprocess, extractTDoc } from './parser';
 export { dialectForFilename, sourceKindForFilename, type Dialect, type SourceKind, } from './dialect';
+export { verifyPredicate, compilePredicate, suggest, effectfulFromAtoms, formatPredicateDiagnostics, PredicateFuelExhausted, type PredicateDiagnostic, type PredicateVerifyResult, type VerifyPredicateOptions, type CompilePredicateOptions, type Suggestion, type SuggestOptions, } from './predicate';
+export { compilePredicateSchema, validatePredicateSchema, type PredicateSchema, type SchemaError, type SchemaValidationResult, type PredicateSchemaOptions, } from './predicate-schema';
 export { transformFunction } from './emitters/ast';
 export { transpileToJS } from './emitters/js';
 export type { TJSTranspileOptions, TJSTranspileResult, TJSTypeInfo, } from './emitters/js';

package/dist/src/vm/runtime.d.ts

@@ -89,6 +89,17 @@ export interface RuntimeContext {
     callDepth?: number;
 }
 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;
@@ -97,6 +108,7 @@ export interface AtomDef {
     docs?: string;
     timeoutMs?: number;
     cost?: number | ((input: any, ctx: RuntimeContext) => number);
+    effects?: AtomEffects;
 }
 export interface Atom<I, O> extends AtomDef {
     create(input: I): I & {
@@ -107,6 +119,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 {
     result: any;
@@ -349,3 +363,11 @@ export declare const coreAtoms: {
     releaseProcedure: Atom<Record<string, any>, boolean>;
     clearExpiredProcedures: Atom<Record<string, any>, number>;
 };
+/**
+ * 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 declare const EFFECTFUL_CORE_OPS: readonly ["httpFetch", "storeGet", "storeSet", "storeQuery", "storeVectorSearch", "llmPredict", "agentRun", "transpileCode", "runCode", "random", "uuid", "consoleLog", "consoleWarn", "consoleError", "storeProcedure", "releaseProcedure", "clearExpiredProcedures", "cache", "memoize"];