Host API Reference

import {
  parse,
  execute,
  createRuntimeContext,
  toCallable,
  RuntimeHaltSignal,
  type ExtensionFactoryResult,
} from '@rcrsr/rill';

function createMyExtension(config: { model: string }): ExtensionFactoryResult {
  return {
    value: {
      prompt: toCallable({
        params: [{ name: 'text', type: { kind: 'string' } }],
        fn: async (args) => await callLLM(args.text, config.model),
        annotations: { description: 'Send a prompt to the LLM' },
        returnType: { kind: 'string' },
      }),
    },
  };
}

const ext = createMyExtension({ model: 'claude-3-5-sonnet' });
const controller = new AbortController();

const ctx = createRuntimeContext({
  variables: { llm: ext.value },
  callbacks: { onLog: (value) => console.log('[log]', value) },
  timeout: 30000,
  signal: controller.signal,
});

try {
  const ast = parse('llm.prompt("Hello")');
  const result = await execute(ast, ctx);
  console.log('Result:', result.result);
} catch (err) {
  if (err instanceof RuntimeHaltSignal) {
    console.log('Cancelled');
  } else {
    throw err;
  }
} finally {
  await ext.dispose?.();
}

import {
  parse,
  execute,
  createRuntimeContext,
  callable,
  structureToTypeValue,
  RuntimeHaltSignal,
  type RillValue,
} from '@rcrsr/rill';

const script = `
  $config.greeting -> prompt() => $response
  $response
`;

const controller = new AbortController();

const ctx = createRuntimeContext({
  variables: {
    config: {
      greeting: 'Say hello in French',
    },
    utils: {
      // Property-style callable (computed property)
      timestamp: callable(() => Date.now(), true),
      // Untyped callable: params is undefined, args is RillValue[] (no marshaling)
      format: callable((args) => {
        const [template, ...values] = args as unknown as RillValue[];
        return String(template).replace(/\{\}/g, () =>
          String(values.shift() ?? '')
        );
      }),
    },
  },

  functions: {
    prompt: {
      params: [{ name: 'text', type: { kind: 'string' } }],
      fn: async (args, ctx, location) => {
        console.log(`[prompt at line ${location?.line}]`);
        return await callLLM(args.text);
      },
      annotations: { description: 'Send a prompt to the LLM and return the response' },
      returnType: structureToTypeValue({ kind: 'string' }),
    },
  },

  callbacks: {
    onLog: (value) => console.log('[log]', value),
  },

  observability: {
    onStepStart: (e) => console.log(`Step ${e.index + 1}...`),
    onStepEnd: (e) => console.log(`Done (${e.durationMs}ms)`),
  },

  timeout: 30000,
  signal: controller.signal,
});

try {
  const ast = parse(script);
  const result = await execute(ast, ctx);
  console.log('Result:', result.result);
} catch (err) {
  if (err instanceof RuntimeHaltSignal) {
    console.log('Cancelled');
  } else {
    throw err;
  }
}

// Parsing
export { parse, parseWithRecovery, parseTypeRef, createParserState, tokenize, LexerError };
export { KEYWORDS };
export type { ParseResult, RecoveryErrorNode, ErrorNode, ParseOptions };

// Execution
export { execute, createRuntimeContext, createStepper, generateManifest };
export type { RuntimeContext, RuntimeOptions, ExecutionResult };
export type { ExecutionStepper, StepResult };

// Execution context (advanced use)
export { createChildContext, getVariable, hasVariable };
export { getCallStack, pushCallFrame, popCallFrame };
export { invokeCallable };
export type { ControlFlowContext, DispatchContext, LifecycleContext, MetadataContext, ResolverContext, ScopeContext };
export type { FieldComparisonCallbacks, CallFrame };

// Resolvers
export { moduleResolver, extResolver, contextResolver };
export type { SchemeResolver, ResolverResult };

// Dispatch-boundary policy
export { createConfigFilterResolver, resolvePolicy, getExtensionIdentity };
export type { Filter, FilterResolver, ExtensionIdentity };
export type { PolicyConfig, ExtensionMethodPolicy, MethodPolicyRule, ResolvedPolicy };

// Callable types
export { callable, isCallable, isScriptCallable, isRuntimeCallable, isApplicationCallable, hydrateFieldDefaults };
export type { RillCallable, ScriptCallable, ApplicationCallable, CallableFn };

// Host function types
export type { RillParam, RillFunction };
export type { TypeStructure };
export type { TypeDefinition, TypeProtocol };
export type { RillTypeValue };
export type { MarshalOptions };
export { marshalArgs };

// Stream helpers
export { createRillStream, isRillStream };
export type { RillStream };

// Value types
export type { RillValue };
export type { RillAtomValue, RillDatetime, RillDuration, RillFieldDef, RillIterator, RillTuple, RillVector };
export type { TraceKind };

// Value conversion
export { toNative };
export type { NativeResult, NativeValue, NativeArray, NativePlainObject };

// Value construction and inspection
export { copyValue, createOrdered, createTuple, createVector };
export {
  getStatus,
  isAtom,
  isDatetime,
  isDuration,
  isInvalid,
  isIterator,
  isStream,
  isTuple,
  isTypeValue,
  isVacant,
  isVector,
};
export {
  commonType,
  compareStructuredFields,
  formatRillLiteral,
  formatStructure,
  inferStructure,
  structureEquals,
  structureMatches,
};
export { BUILT_IN_TYPES, deepEquals, deserializeValue, formatValue, inferType, serializeValue };
export { anyTypeValue, isEmpty, structureToTypeValue };
export { formatHalt };

// Field descriptors
export { buildFieldDescriptor };
export type { ConfigFieldDescriptor };

// Introspection
export { getFunctions, getLanguageReference, getDocumentationCoverage, introspectHandlerFromAST };
export type { FunctionMetadata, ParamMetadata, DocumentationCoverageResult, HandlerMetadataStatic, HandlerParamStatic };

// Version information
export { VERSION, VERSION_INFO };
export type { VersionInfo };

// Callbacks
export type { RuntimeCallbacks, ObservabilityCallbacks };
export type { StepStartEvent, StepEndEvent, HostCallEvent, FunctionReturnEvent };
export type { CaptureEvent, ErrorEvent };

// Errors
export { RillError, RuntimeError, ParseError, TimeoutError };
export { formatRillError, formatRillErrorJson, createError, renderMessage, getHelpUrl };
export { ERROR_HANDLING_PATTERNS };
export type { ErrorHandlingExample, ErrorHandlingPattern, ErrorExample, ErrorRegistry };
export type { ErrorCategory, ErrorDefinition, ErrorSeverity };
export type { FormatErrorOptions, FormatErrorJsonOptions, SourceMap };

// Utilities
export { isDict };
export type { SourceLocation, SourceSpan };

// Control flow (for advanced use)
export { BreakSignal, ReturnSignal, YieldSignal, ControlSignal, RuntimeHaltSignal };

// Syntax highlighting
export { TOKEN_HIGHLIGHT_MAP };
export type { HighlightCategory };

// Error registry
export { ERROR_REGISTRY };

// Language and tooling metadata
export { BUILTIN_FUNCTIONS, BUILTIN_METHODS, KEYWORDS, TOKEN_TYPES, VALID_TYPE_NAMES };
export type { Token, TokenType };

// Extension types
export type { ExtensionFactoryResult, ExtensionFactory, ExtensionEvent, ExtensionManifest, ExtensionConfigSchema };
export type { ExtensionFactoryCtx };

// Extension utilities
export { toCallable, createTestContext, emitExtensionEvent };
export { ExtensionBindingError };

// Atom registry (read-only access at top level)
export { resolveAtom, atomName };
export type { InvalidateMeta, TraceFrame };

// AST node types
export { isPipeChainNode };
export type {
  AnnotatedExprNode,
  AnnotatedStatementNode,
  AnnotationAccessNode,
  AnnotationArg,
  ArithHead,
  AssertNode,
  ASTNode,
  AtomLiteralNode,
  BinaryExprNode,
  BinaryOp,
  BlockNode,
  BodyNode,
  BoolLiteralNode,
  BracketAccess,
  BreakNode,
  CaptureNode,
  ChainTerminator,
  ClosureCallNode,
  ClosureNode,
  ClosureParamNode,
  ClosureSigLiteralNode,
  ConditionalNode,
  DestructNode,
  DestructPatternNode,
  DestructureNode,
  DictEntryNode,
  DictKeyComputed,
  DictKeyVariable,
  DictLiteralNode,
  DictNode,
  DoWhileLoopNode,
  ExistenceCheck,
  ExpressionNode,
  FieldAccess,
  FieldAccessAlternatives,
  FieldAccessAnnotation,
  FieldAccessBlock,
  FieldAccessComputed,
  FieldAccessLiteral,
  FieldAccessVariable,
  FrontmatterNode,
  GroupedExprNode,
  GuardBlockNode,
  HostCallNode,
  HostRefNode,
  InterpolationNode,
  InvokeNode,
  ListLiteralNode,
  ListSpreadNode,
  LiteralNode,
  MethodCallNode,
  NamedArgNode,
  NumberLiteralNode,
  OrderedLiteralNode,
  PartialExpressionNode,
  PassNode,
  PipeChainNode,
  PipeInvokeNode,
  PipeTargetNode,
  PostfixExprNode,
  PrimaryNode,
  PropertyAccess,
  RetryBlockNode,
  ReturnNode,
  ScriptNode,
  SimplePrimaryNode,
  SliceBoundNode,
  SliceNode,
  SpreadArgNode,
  StatementNode,
  StatusProbeNode,
  StringLiteralNode,
  TimeoutBlockNode,
  TupleLiteralNode,
  TypeAssertionNode,
  TypeCheckNode,
  TypeConstructorNode,
  TypeNameExprNode,
  UnaryExprNode,
  UseExprNode,
  UseIdentifier,
  VariableNode,
  WhileLoopNode,
  YieldNode,
};
export type { NodeType };
export type { FieldArg, RillTypeName, TypeRef };

// AST traversal
export { nodeAtPosition, walkAst };

interface NativeResult {
  /** Base rill type name — matches RillTypeName, or "iterator" for lazy sequences */
  rillTypeName: string;
  /** Full structural signature from formatStructure,
   *  e.g. "list(number)", "dict(a: number, b: string)", "|x: number| :string" */
  rillTypeSignature: string;
  /** JS-native representation. Always populated — never undefined.
   *  Non-native types produce descriptor objects. */
  value: NativeValue;
}

type NativeValue =
  | string | number | boolean | null
  | NativeArray | NativePlainObject;

import { createRuntimeContext } from '@rcrsr/rill';

// Fixed timestamp for deterministic test execution
const ctx = createRuntimeContext({
  timezone: -5,
  nowMs: new Date('2024-06-15T12:00:00Z').getTime(),
});

// Scripts using now() return 2024-06-15T12:00:00Z
// Scripts using .local_date return date in UTC-5 (2024-06-15)

import { TOKEN_HIGHLIGHT_MAP, tokenize } from '@rcrsr/rill';

const tokens = tokenize(source);
for (const token of tokens) {
  const category = TOKEN_HIGHLIGHT_MAP.get(token.type);
  if (category) applyHighlight(token, category);
}

import { ERROR_REGISTRY, getHelpUrl } from '@rcrsr/rill';

const entry = ERROR_REGISTRY.get('RILL-P008');
console.log(entry?.description);  // "Bare bracket at expression start"
console.log(getHelpUrl('RILL-P008', '0.4.1'));  // "https://github.com/rcrsr/rill/blob/v0.4.1/docs/ref-errors.md#rill-p008"

import { parseWithRecovery } from '@rcrsr/rill';

const result = parseWithRecovery(source);
if (!result.success) {
  console.log('Errors:', result.errors);
}
// result.ast may contain RecoveryErrorNode or PartialExpressionNode entries

import { nodeAtPosition, parse } from '@rcrsr/rill';

const ast = parse(source);
const node = nodeAtPosition(ast, 42);
if (node !== null) {
  console.log('Node at offset 42:', node.type);
}

import { walkAst, parse } from '@rcrsr/rill';

const ast = parse(source);
const types: string[] = [];
walkAst(ast, (node) => {
  types.push(node.type);
});

import { BUILTIN_FUNCTIONS } from '@rcrsr/rill';

const completions = BUILTIN_FUNCTIONS.map((name) => ({ label: name }));
registerCompletionProvider(completions);

import { KEYWORDS } from '@rcrsr/rill';

const keywordSet = new Set(KEYWORDS);
const isKeyword = (token: string) => keywordSet.has(token);

interface RillParam {
  readonly name: string;
  readonly type: TypeStructure | undefined;
  readonly defaultValue: RillValue | undefined;
  readonly annotations: Record<string, RillValue>;
}

type CallableFn = (
  args: Record<string, RillValue>,
  ctx: RuntimeContextLike,
  location?: SourceLocation
) => RillValue | Promise<RillValue>;

import { getTypedKeyEntries } from '@rcrsr/rill';

const fn: CallableFn = (args) => {
  const someDict = args.someDict; // dict[1: "a", "1": "b"]
  Object.keys(someDict); // -> ["1"], the number key 1 is missing
  return getTypedKeyEntries(someDict); // -> [{ key: 1, value: "a" }]
};

interface RillFunction {
  readonly params: readonly RillParam[];
  readonly fn: CallableFn;
  readonly annotations?: Record<string, RillValue>;
  readonly returnType: RillTypeValue;
}

const fn: RillFunction = {
  params: [{
    name: 'coords',
    type: {
      kind: 'tuple',
      fields: [
        { type: { kind: 'number' } },
        { type: { kind: 'number' }, defaultValue: 0 },  // default: 0
      ],
    },
  }],
  fn: (args) => args.coords,  // caller passes tuple[1] → receives tuple[1, 0]
  returnType: structureToTypeValue({ kind: 'tuple' }),
};

createRillStream(options: {
  chunks: AsyncIterable<RillValue>;
  resolve: () => Promise<RillValue>;
  dispose?: () => void;
  chunkType?: TypeStructure;
  retType?: TypeStructure;
}): RillStream

import { createRillStream } from '@rcrsr/rill';
import type { RillValue } from '@rcrsr/rill';

const fn: RillFunction = {
  params: [{ name: 'prompt', type: { kind: 'string' } }],
  fn: async (args) => {
    async function* generateChunks(): AsyncIterable<RillValue> {
      for await (const token of streamLLM(args.prompt as string)) {
        yield token as RillValue;
      }
    }
    return createRillStream({
      chunks: generateChunks(),
      resolve: async () => 'done' as RillValue,
    });
  },
  returnType: structureToTypeValue({ kind: 'stream', chunk: { kind: 'string' }, ret: { kind: 'string' } }),
};

isRillStream(value: RillValue): value is RillStream

import { isRillStream } from '@rcrsr/rill';
import type { RillStream } from '@rcrsr/rill';

import { parse, execute, createRuntimeContext, isRillStream } from '@rcrsr/rill';
import type { RillStream } from '@rcrsr/rill';

const ast = parse('use<ext:app> => $app\n$app.stream_fn("prompt text")');
const ctx = createRuntimeContext({ /* ... */ });
const result = await execute(ast, ctx);

if (isRillStream(result.result)) {
  let step = result.result as RillStream;

  // Advance through chunks; initial stream object has no value — call next first
  step = (await step.next.fn({}, ctx)) as RillStream;
  while (!step.done) {
    console.log('chunk:', step.value);
    step = (await step.next.fn({}, ctx)) as RillStream;
  }

  // Invoke the resolution callback via the hidden resolve property
  const resolveFn = (step as unknown as Record<string, () => Promise<unknown>>)[
    '__rill_stream_resolve'
  ];
  const finalValue = resolveFn ? await resolveFn() : undefined;
  console.log('resolved:', finalValue);
}

import { generateManifest } from '@rcrsr/rill';

const manifest = generateManifest(ctx);
// Returns a rill file suitable for static analysis or LLM context

[
  "greet": |^("who") name: string|:string,
  "fetch": |url: string|:dict,
  "now": ||:number
]

type SchemeResolver = (
  resource: string,
  config?: unknown
) => ResolverResult | Promise<ResolverResult>;

import type { SchemeResolver } from '@rcrsr/rill';

const myResolver: SchemeResolver = async (resource, config) => {
  const source = await loadSource(resource);
  return { kind: 'source', text: source };
};

type ResolverResult =
  | { kind: 'value'; value: RillValue }
  | { kind: 'source'; text: string };

import type { ResolverResult, RillValue } from '@rcrsr/rill';

// Return a pre-built value
const valueResult: ResolverResult = {
  kind: 'value',
  value: { search: mySearchFn } as RillValue,
};

// Return source text for rill to parse
const sourceResult: ResolverResult = {
  kind: 'source',
  text: `|x: string| x -> .upper`,
};

import { moduleResolver } from '@rcrsr/rill';

import { moduleResolver, createRuntimeContext } from '@rcrsr/rill';

const ctx = createRuntimeContext({
  resolvers: { host: moduleResolver },
  configurations: {
    resolvers: {
      host: {
        utils: './utils.rill',
        helpers: './lib/helpers.rill',
      },
    },
  },
});

// Scripts can now use: use<host:utils>

import { extResolver } from '@rcrsr/rill';

import { extResolver, createRuntimeContext } from '@rcrsr/rill';
import { qdrantExtension } from './my-qdrant-ext';

const ctx = createRuntimeContext({
  resolvers: { ext: extResolver },
  configurations: {
    resolvers: {
      ext: {
        qdrant: qdrantExtension,
      },
    },
  },
});

// Scripts can now use: use<ext:qdrant> or use<ext:qdrant.search>

function resolvePolicy(
  config: PolicyConfig,
  extensions: ReadonlyMap<string, RillValue>
): ResolvedPolicy;

function createConfigFilterResolver(policy: ResolvedPolicy): FilterResolver;

function getExtensionIdentity(
  callable: RillCallable
): ExtensionIdentity | undefined;

interface FilterResolver {
  (
    callable: RillCallable,
    resolvedPath: string | undefined,
    ctx: RuntimeContext
  ): Filter | null;

  readonly policesExtension?: (extension: string) => boolean;
}

interface Filter {
  readonly access: 'allow' | 'deny';
  readonly inTransforms: readonly RillCallable[];
  readonly outTransforms: readonly RillCallable[];
}

interface ExtensionIdentity {
  readonly extension: string;
  readonly method: string;
}

interface MethodPolicyRule {
  readonly access: 'allow' | 'deny';
  readonly in?: readonly string[];
  readonly out?: readonly string[];
}

type ExtensionMethodPolicy = Record<string, MethodPolicyRule>;
type PolicyConfig = Record<string, ExtensionMethodPolicy>;

interface ResolvedPolicy {
  readonly rules: ReadonlyMap<string, ReadonlyMap<string, Filter>>;
  readonly defaults: ReadonlyMap<string, Filter>;
}

interface ExtensionFactoryCtx {
  registerErrorCode(name: string, kind: string): void;
  readonly signal: AbortSignal;
}

type ExtensionFactory<TConfig> = (
  config: TConfig,
  ctx: ExtensionFactoryCtx
) => ExtensionFactoryResult | Promise<ExtensionFactoryResult>;

async function createPaymentExtension(
  config: PaymentConfig,
  ctx: ExtensionFactoryCtx
): Promise<ExtensionFactoryResult> {
  ctx.registerErrorCode('PAYMENT_FAILED', 'domain');
  ctx.registerErrorCode('CARD_DECLINED', 'domain');

  const client = await PaymentClient.connect(config.endpoint, {
    signal: ctx.signal,
  });

  return {
    value: {
      charge: toCallable({ /* ... */ }),
    },
    dispose: () => client.close(),
  };
}

invalidate(error: unknown, meta: InvalidateMeta): RillValue

fn: async (args, ctx) => {
  try {
    return await sdkClient.fetch(args.url as string);
  } catch (e) {
    return ctx.invalidate(e, { code: 'UNAVAILABLE', provider: 'my-ext' });
  }
},

catch<T>(
  thunk: () => Promise<T>,
  detector: (e: unknown) => InvalidMeta | null
): Promise<T | RillValue>

fn: async (args, ctx) => {
  return ctx.catch(
    () => sdkClient.fetch(args.url as string),
    (e) => {
      if (e instanceof TimeoutError) return { code: 'TIMEOUT', provider: 'my-ext' };
      if (e instanceof AuthError) return { code: 'AUTH', provider: 'my-ext' };
      return null; // re-throw unknown errors
    }
  );
},

readonly signal: AbortSignal | undefined

fn: async (args, ctx) => {
  const response = await fetch(args.url as string, {
    signal: ctx.signal,
  });
  return response.text();
},

function dispose(): Promise<void>

import { parse, execute, createRuntimeContext, dispose } from '@rcrsr/rill';

const ctx = createRuntimeContext({ /* ... */ });

try {
  const result = await execute(parse(script), ctx);
  console.log(result.result);
} finally {
  await dispose();
}