@objectstack/formula 4.0.4

package/src/normalize.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest';
+import { cel, F, P } from '@objectstack/spec';
+
+import { normalizeExpression, normalizeExpressionTree } from './normalize';
+
+describe('cel/F/P tagged templates', () => {
+  it('cel`...` produces an Expression envelope with dialect=cel', () => {
+    const e = cel`record.amount > 1000`;
+    expect(e).toEqual({ dialect: 'cel', source: 'record.amount > 1000' });
+  });
+
+  it('F is a cel alias for formulas', () => {
+    expect(F`1 + 1`).toEqual({ dialect: 'cel', source: '1 + 1' });
+  });
+
+  it('P is a cel alias for predicates', () => {
+    expect(P`x == 1`).toEqual({ dialect: 'cel', source: 'x == 1' });
+  });
+
+  it('JSON-escapes interpolated strings', () => {
+    const name = "O'Brien";
+    const e = cel`record.owner == ${name}`;
+    expect(e.source).toBe('record.owner == "O\'Brien"');
+  });
+
+  it('passes numbers and booleans through unchanged', () => {
+    const e = cel`record.x > ${100} && record.flag == ${true}`;
+    expect(e.source).toBe('record.x > 100 && record.flag == true');
+  });
+});
+
+describe('normalizeExpression', () => {
+  it('lifts bare strings to {dialect:cel,source} and adds ast', () => {
+    const r = normalizeExpression('1 + 1');
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.value.dialect).toBe('cel');
+      expect(r.value.source).toBe('1 + 1');
+      expect(r.value.ast).toBeDefined();
+    }
+  });
+
+  it('compiles existing source expressions adding ast', () => {
+    const r = normalizeExpression({ dialect: 'cel', source: 'record.x > 1' });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.value.ast).toBeDefined();
+  });
+
+  it('returns parse error with kind=parse', () => {
+    const r = normalizeExpression('1 +');
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe('normalizeExpressionTree', () => {
+  it('walks nested objects and adds ast in place', () => {
+    const tree = {
+      view: {
+        visible: { dialect: 'cel', source: 'record.x > 1' },
+      },
+      action: {
+        disabled: { dialect: 'cel', source: 'record.locked' },
+      },
+    };
+    const err = normalizeExpressionTree(tree);
+    expect(err).toBeNull();
+    expect((tree.view.visible as { ast: unknown }).ast).toBeDefined();
+    expect((tree.action.disabled as { ast: unknown }).ast).toBeDefined();
+  });
+
+  it('walks arrays', () => {
+    const tree = {
+      rules: [
+        { condition: { dialect: 'cel', source: 'record.a > 1' } },
+        { condition: { dialect: 'cel', source: 'record.b == "x"' } },
+      ],
+    };
+    const err = normalizeExpressionTree(tree);
+    expect(err).toBeNull();
+    for (const r of tree.rules) expect((r.condition as { ast: unknown }).ast).toBeDefined();
+  });
+
+  it('reports the dotted path of the offending node on error', () => {
+    const tree = {
+      objects: { task: { hooks: { 0: { condition: { dialect: 'cel', source: '1 +' } } } } },
+    };
+    const err = normalizeExpressionTree(tree);
+    expect(err).not.toBeNull();
+    expect(err!.path).toContain('condition');
+  });
+
+  it('ignores non-Expression objects', () => {
+    const tree = { dialect: 'something', notAnExpression: true };
+    const err = normalizeExpressionTree(tree);
+    expect(err).toBeNull();
+    // Tree should be unchanged
+    expect((tree as { ast?: unknown }).ast).toBeUndefined();
+  });
+});

package/src/normalize.ts

@@ -0,0 +1,103 @@
+/**
+ * Build-time normalization helpers.
+ *
+ * The CLI `objectstack compile` step walks the assembled `objectstack.json`
+ * artifact and rewrites every Expression so that:
+ *
+ *  1. String shorthand input is replaced by `{ dialect: 'cel', source }`.
+ *  2. The persisted envelope carries an `ast` field produced by the dialect
+ *     engine (M9.2 deliverable). Source is retained for round-trip / debug.
+ *
+ * Spec layer cannot do step 2 because it must remain dependency-free; this
+ * package owns the engine import and therefore the AST step.
+ */
+
+import {
+  ExpressionInputSchema,
+  ExpressionSchema,
+  type Expression,
+  type ExpressionInput,
+} from '@objectstack/spec';
+
+import { ExpressionEngine } from './registry';
+import type { EvalResult } from './types';
+
+/**
+ * Normalize an {@link ExpressionInput} (string shorthand OR full envelope) into
+ * a fully-resolved {@link Expression} carrying both `source` and `ast`.
+ *
+ * Returns an EvalResult so the caller can render a structured compile error
+ * pointing at the offending metadata path.
+ */
+export function normalizeExpression(input: ExpressionInput): EvalResult<Expression> {
+  const parsed = ExpressionInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: { kind: 'parse', message: parsed.error.message },
+    };
+  }
+
+  const expr = parsed.data as Expression;
+
+  // Already AST-only — accept as-is.
+  if (expr.ast !== undefined && expr.source === undefined) {
+    return { ok: true, value: expr };
+  }
+
+  // Source-bearing: ask the dialect engine to compile. Failures surface here
+  // as part of the build (no silent skip).
+  const compiled = ExpressionEngine.compile(expr);
+  if (!compiled.ok) {
+    return compiled;
+  }
+
+  return {
+    ok: true,
+    value: {
+      ...expr,
+      ast: compiled.value,
+    },
+  };
+}
+
+/**
+ * Walk an arbitrary JSON tree and normalize every embedded Expression in
+ * place. Used by the build pipeline to traverse the assembled metadata
+ * artifact. Returns the first error encountered (paired with the dotted path
+ * for diagnostics) or `null` when fully clean.
+ */
+export function normalizeExpressionTree(
+  root: unknown,
+  path: string[] = [],
+): { path: string; error: import('./types').EvalError } | null {
+  if (root === null || typeof root !== 'object') return null;
+
+  if (looksLikeExpression(root)) {
+    const r = normalizeExpression(root as ExpressionInput);
+    if (!r.ok) return { path: path.join('.'), error: r.error };
+    Object.assign(root as Record<string, unknown>, r.value);
+    return null;
+  }
+
+  if (Array.isArray(root)) {
+    for (let i = 0; i < root.length; i++) {
+      const r = normalizeExpressionTree(root[i], [...path, String(i)]);
+      if (r) return r;
+    }
+    return null;
+  }
+
+  for (const [k, v] of Object.entries(root as Record<string, unknown>)) {
+    const r = normalizeExpressionTree(v, [...path, k]);
+    if (r) return r;
+  }
+  return null;
+}
+
+function looksLikeExpression(value: unknown): boolean {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.dialect !== 'string') return false;
+  return ExpressionSchema.safeParse(v).success;
+}

package/src/registry.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+
+import { ExpressionEngine, getEngine, hasDialect } from './registry';
+import type { Expression } from '@objectstack/spec';
+
+describe('ExpressionEngine registry', () => {
+  it('routes cel dialect to celEngine', () => {
+    const expr: Expression = { dialect: 'cel', source: '1 + 1' };
+    const r = ExpressionEngine.evaluate(expr, {});
+    expect(r).toEqual({ ok: true, value: 2 });
+  });
+
+  it('returns dialect error for js stub', () => {
+    const expr: Expression = { dialect: 'js', source: 'foo' };
+    const r = ExpressionEngine.evaluate(expr, {});
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.kind).toBe('dialect');
+  });
+
+  it('returns dialect error for cron stub', () => {
+    const expr: Expression = { dialect: 'cron', source: '* * * * *' };
+    const r = ExpressionEngine.evaluate(expr, {});
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.kind).toBe('dialect');
+  });
+
+  it('returns dialect error for unknown dialect', () => {
+    const r = ExpressionEngine.evaluate({ dialect: 'xyz' as never, source: 'x' }, {});
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.kind).toBe('dialect');
+  });
+
+  it('compile() emits AST for valid CEL source', () => {
+    const r = ExpressionEngine.compile({ dialect: 'cel', source: 'record.x > 1' });
+    expect(r.ok).toBe(true);
+  });
+
+  it('getEngine returns registered engine', () => {
+    expect(getEngine('cel')?.dialect).toBe('cel');
+    expect(getEngine('js')?.dialect).toBe('js');
+    expect(getEngine('nonexistent')).toBeUndefined();
+  });
+
+  it('hasDialect distinguishes real engines from stubs', () => {
+    expect(hasDialect('cel')).toBe(true);
+  });
+});

package/src/registry.ts

@@ -0,0 +1,94 @@
+/**
+ * Dialect-pluggable Expression engine registry.
+ *
+ * Replaces the per-call-site `compileFormula` / `evaluateFormula` direct
+ * imports of the deleted custom engine. Call sites now ask the registry to
+ * dispatch by `expression.dialect`.
+ *
+ * Stub dialects (`js`, `cron`) are registered at module load with explicit
+ * `dialect`-error responses so call sites get a clear message instead of
+ * silent `undefined` (the old engine's anti-pattern).
+ */
+
+import type { Expression } from '@objectstack/spec';
+
+import { celEngine } from './cel-engine';
+import type { DialectEngine, EvalContext, EvalResult } from './types';
+
+const registry = new Map<string, DialectEngine>();
+
+/** Register or replace a dialect engine. */
+export function register(engine: DialectEngine): void {
+  registry.set(engine.dialect, engine);
+}
+
+/** Look up a dialect engine without dispatching. */
+export function getEngine(dialect: string): DialectEngine | undefined {
+  return registry.get(dialect);
+}
+
+/** Whether a dialect has a real (non-stub) implementation registered. */
+export function hasDialect(dialect: string): boolean {
+  return registry.has(dialect) && !registry.get(dialect)!.dialect.startsWith('stub:');
+}
+
+function makeStub(dialect: string, reason: string): DialectEngine {
+  return {
+    dialect,
+    compile: () => ({ ok: false, error: { kind: 'dialect', message: reason } }),
+    evaluate: () => ({ ok: false, error: { kind: 'dialect', message: reason } }),
+  };
+}
+
+// Real engines.
+register(celEngine);
+
+// Stubs — phased in by later milestones (M9.5+ for `js`, M9.6 for `cron`).
+register(makeStub('js', "dialect 'js' not registered. Install @objectstack/plugin-js-vm"));
+register(makeStub('cron', "dialect 'cron' not registered. Install @objectstack/plugin-cron"));
+
+/**
+ * The unified evaluation entry point. Replaces the old direct calls to
+ * `evaluateFormula` from the deleted custom engine.
+ */
+export const ExpressionEngine = {
+  register,
+  getEngine,
+  hasDialect,
+
+  /**
+   * Compile-only — parse + type-check, returning the engine-native AST. Used
+   * by `objectstack compile` to normalize source into AST in artifacts.
+   */
+  compile(expr: Expression): EvalResult<unknown> {
+    const engine = registry.get(expr.dialect);
+    if (!engine) {
+      return {
+        ok: false,
+        error: { kind: 'dialect', message: `No engine registered for dialect '${expr.dialect}'` },
+      };
+    }
+    if (typeof expr.source !== 'string') {
+      return {
+        ok: false,
+        error: { kind: 'parse', message: 'Expression.source required for compile()' },
+      };
+    }
+    return engine.compile(expr.source);
+  },
+
+  /**
+   * Evaluate an expression in the given context. Never throws — branch on
+   * `result.ok`. Errors carry a `kind` for caller-side classification.
+   */
+  evaluate<T = unknown>(expr: Expression, ctx: EvalContext): EvalResult<T> {
+    const engine = registry.get(expr.dialect);
+    if (!engine) {
+      return {
+        ok: false,
+        error: { kind: 'dialect', message: `No engine registered for dialect '${expr.dialect}'` },
+      };
+    }
+    return engine.evaluate<T>(expr, ctx);
+  },
+};

package/src/seed-eval.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveSeed, resolveSeedRecord } from './seed-eval';
+import type { Expression } from '@objectstack/spec';
+
+const cel = (source: string): Expression => ({ dialect: 'cel', source });
+
+describe('resolveSeed', () => {
+  it('passes through primitives unchanged', () => {
+    expect(resolveSeed('hello', {})).toEqual({ ok: true, value: 'hello' });
+    expect(resolveSeed(42, {})).toEqual({ ok: true, value: 42 });
+    expect(resolveSeed(true, {})).toEqual({ ok: true, value: true });
+    expect(resolveSeed(null, {})).toEqual({ ok: true, value: null });
+  });
+
+  it('passes through Date objects unchanged', () => {
+    const d = new Date('2026-01-01T00:00:00Z');
+    const r = resolveSeed(d, {});
+    expect(r).toEqual({ ok: true, value: d });
+  });
+
+  it('evaluates Expression leaves with provided context', () => {
+    const pinned = new Date('2026-01-15T10:00:00Z');
+    const r = resolveSeed(cel('daysFromNow(30)'), { now: pinned });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect((r.value as Date).toISOString()).toBe('2026-02-14T10:00:00.000Z');
+  });
+
+  it('walks arrays', () => {
+    const r = resolveSeed([1, cel('2 + 2'), 'x'], {});
+    expect(r).toEqual({ ok: true, value: [1, 4, 'x'] });
+  });
+
+  it('walks nested objects', () => {
+    const r = resolveSeed(
+      {
+        name: 'Acme',
+        meta: { score: cel('10 * 2') },
+      },
+      {},
+    );
+    expect(r).toEqual({ ok: true, value: { name: 'Acme', meta: { score: 20 } } });
+  });
+
+  it('returns first error encountered', () => {
+    const r = resolveSeed(
+      {
+        a: 1,
+        bad: cel('1 +'),
+        c: 3,
+      },
+      {},
+    );
+    expect(r.ok).toBe(false);
+  });
+
+  it('resolveSeedRecord pins now() so multiple expressions see same clock', () => {
+    const r = resolveSeedRecord(
+      {
+        a: cel('now()'),
+        b: cel('now()'),
+      },
+      {},
+    );
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      const a = (r.value.a as Date).toISOString();
+      const b = (r.value.b as Date).toISOString();
+      expect(a).toBe(b);
+    }
+  });
+
+  it('honors explicit ctx.now snapshot', () => {
+    const pinned = new Date('2026-06-01T12:00:00Z');
+    const r = resolveSeedRecord(
+      { close_date: cel('daysFromNow(30)') },
+      { now: pinned },
+    );
+    expect(r.ok).toBe(true);
+    if (r.ok)
+      expect((r.value.close_date as Date).toISOString()).toBe('2026-07-01T12:00:00.000Z');
+  });
+});

package/src/seed-eval.ts

@@ -0,0 +1,81 @@
+/**
+ * Seed-value resolver.
+ *
+ * `Dataset.records` accepts {@link SeedValue} = primitive | Expression | array
+ * | object — install-time resolution walks the tree and replaces any
+ * Expression node with its evaluated result. This is what makes
+ * `close_date: cel\`now() + duration("P30D")\`` resolve to *the customer's*
+ * "today + 30 days" instead of the developer's compile-time clock.
+ */
+
+import { ExpressionSchema, type Expression } from '@objectstack/spec';
+
+import type { EvalContext, EvalResult } from './types';
+import { ExpressionEngine } from './registry';
+
+export type SeedPrimitive = string | number | boolean | null | Date;
+export type SeedValue = SeedPrimitive | Expression | SeedValue[] | { [key: string]: SeedValue };
+
+/** Detect an Expression-shaped object without throwing on unrelated shapes. */
+function isExpressionLike(value: unknown): value is Expression {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.dialect !== 'string') return false;
+  return ExpressionSchema.safeParse(v).success;
+}
+
+/**
+ * Recursively resolve a SeedValue. Records that contain Expression leaves are
+ * evaluated with `ctx`; other values are passed through unchanged.
+ *
+ * Returns the first failure encountered. Callers (seed loader) typically
+ * abort the whole record on failure rather than silently writing partial data.
+ */
+export function resolveSeed(
+  value: SeedValue,
+  ctx: EvalContext,
+): EvalResult<unknown> {
+  if (value === null || value === undefined) {
+    return { ok: true, value };
+  }
+  const t = typeof value;
+  if (t === 'string' || t === 'number' || t === 'boolean') {
+    return { ok: true, value };
+  }
+  if (value instanceof Date) {
+    return { ok: true, value };
+  }
+  if (Array.isArray(value)) {
+    const out: unknown[] = [];
+    for (const item of value) {
+      const r = resolveSeed(item, ctx);
+      if (!r.ok) return r;
+      out.push(r.value);
+    }
+    return { ok: true, value: out };
+  }
+  if (isExpressionLike(value)) {
+    return ExpressionEngine.evaluate(value, ctx);
+  }
+  // Plain object — recurse field-by-field.
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, SeedValue>)) {
+    const r = resolveSeed(v, ctx);
+    if (!r.ok) return r;
+    out[k] = r.value;
+  }
+  return { ok: true, value: out };
+}
+
+/**
+ * Resolve a single record (object of fields), pinning `ctx.now` so all
+ * expressions within see one logical clock.
+ */
+export function resolveSeedRecord(
+  record: Record<string, SeedValue>,
+  ctx: EvalContext,
+): EvalResult<Record<string, unknown>> {
+  const pinnedCtx: EvalContext = { ...ctx, now: ctx.now ?? new Date() };
+  const result = resolveSeed(record, pinnedCtx) as EvalResult<Record<string, unknown>>;
+  return result;
+}

package/src/stdlib.ts

@@ -0,0 +1,81 @@
+/**
+ * ObjectStack standard CEL function library.
+ *
+ * Registered into the per-evaluation `Environment` by the CEL engine. All
+ * functions are pure given a pinned `now` — that determinism is what makes
+ * `objectstack build` artifacts byte-stable across runs.
+ *
+ * Function naming intentionally avoids the `os.` prefix because cel-js binds
+ * dotted names to receiver types. Instead, the `os` namespace in CEL holds
+ * *data* (`os.user`, `os.org`, `os.env`) supplied by the caller's
+ * {@link EvalContext}.
+ */
+
+import type { Environment } from '@marcbachmann/cel-js';
+
+import type { EvalContext } from './types';
+
+/** Truncate a Date to start-of-day in UTC. */
+function startOfDayUtc(d: Date): Date {
+  const out = new Date(d.getTime());
+  out.setUTCHours(0, 0, 0, 0);
+  return out;
+}
+
+/** Add `n` days to a Date in UTC; returns a new Date. */
+function addDaysUtc(d: Date, n: number): Date {
+  const out = new Date(d.getTime());
+  out.setUTCDate(out.getUTCDate() + n);
+  return out;
+}
+
+/**
+ * Register the ObjectStack standard library into a CEL environment.
+ *
+ * The `now` resolver is closed over so each call uses the pinned
+ * `EvalContext.now` (or wall-clock fallback). Implementations are kept tiny
+ * and dependency-free — they're the contract surface for AI authors and must
+ * stay legible.
+ */
+export function registerStdLib(
+  env: Environment,
+  now: () => Date,
+): Environment {
+  return env
+    .registerFunction('now(): google.protobuf.Timestamp', () => now())
+    .registerFunction(
+      'today(): google.protobuf.Timestamp',
+      () => startOfDayUtc(now()),
+    )
+    .registerFunction(
+      'daysFromNow(int): google.protobuf.Timestamp',
+      (n: bigint | number) => addDaysUtc(now(), Number(n)),
+    )
+    .registerFunction(
+      'daysAgo(int): google.protobuf.Timestamp',
+      (n: bigint | number) => addDaysUtc(now(), -Number(n)),
+    );
+}
+
+/**
+ * Build the variable scope for a single evaluation. Absent fields are simply
+ * not bound — CEL macros (`has(record.foo)`) handle missing-key safely.
+ */
+export function buildScope(ctx: EvalContext): Record<string, unknown> {
+  const scope: Record<string, unknown> = {};
+
+  if (ctx.record !== undefined) scope.record = ctx.record;
+  if (ctx.previous !== undefined) scope.previous = ctx.previous;
+  if (ctx.input !== undefined) scope.input = ctx.input;
+
+  // Namespaced data — written as `os.user.id`, `os.env`, etc. in CEL.
+  const os: Record<string, unknown> = {};
+  if (ctx.user !== undefined) os.user = ctx.user;
+  if (ctx.org !== undefined) os.org = ctx.org;
+  if (ctx.env !== undefined) os.env = ctx.env;
+  if (Object.keys(os).length > 0) scope.os = os;
+
+  if (ctx.extra !== undefined) Object.assign(scope, ctx.extra);
+
+  return scope;
+}

package/src/types.ts

@@ -0,0 +1,91 @@
+/**
+ * @objectstack/formula — public types
+ *
+ * The expression engine surface is intentionally minimal:
+ *
+ *  - {@link EvalContext}: input passed by call sites (hooks, seed loader, views).
+ *  - {@link EvalResult}: discriminated union — never throws to the caller.
+ *  - {@link DialectEngine}: contract any dialect (cel, js, cron) implements.
+ *
+ * The shape is shared across `cel`, `js` and `cron` so the kernel can route
+ * any persisted `Expression` to the correct engine without conditional logic.
+ */
+
+import type { Expression } from '@objectstack/spec';
+
+/**
+ * Runtime context for evaluating an expression.
+ *
+ * Every field is optional — call sites populate only what they have. The CEL
+ * engine binds `record`, `previous`, `input`, `os` directly as top-level
+ * variables when present.
+ */
+export interface EvalContext {
+  /** Logical "now" snapshot — pinned per evaluation run for determinism. */
+  now?: Date;
+  /** Current authenticated subject (hook / action / view contexts). */
+  user?: {
+    id: string;
+    role?: string;
+    email?: string;
+    [key: string]: unknown;
+  };
+  /** Current organization (multi-tenant context). */
+  org?: {
+    id: string;
+    tier?: string;
+    [key: string]: unknown;
+  };
+  /** Deployment environment marker. */
+  env?: 'prod' | 'dev' | 'test' | string;
+  /** Record-shaped data: target row, hook record, view row, etc. */
+  record?: Record<string, unknown>;
+  /** Previous record state for update hooks. */
+  previous?: Record<string, unknown>;
+  /** Action / flow input payload. */
+  input?: Record<string, unknown>;
+  /**
+   * Optional kernel API for `os.exists / os.count / os.lookup`.
+   * Implemented opportunistically by call sites that have a query engine.
+   */
+  api?: {
+    exists?: (object: string, predicate: Expression) => boolean;
+    count?: (object: string, predicate: Expression) => number;
+    lookup?: (object: string, id: string) => Record<string, unknown> | null;
+  };
+  /** Free-form bag for niche call sites; merged onto the variable scope. */
+  extra?: Record<string, unknown>;
+}
+
+/** Result of a single evaluation. Never throws; callers branch on `ok`. */
+export type EvalResult<T = unknown> =
+  | { ok: true; value: T }
+  | { ok: false; error: EvalError };
+
+/** Structured error so AI callers can self-correct. */
+export interface EvalError {
+  /**
+   * - `parse`     source string failed to parse to AST
+   * - `type`      static type-check failed
+   * - `runtime`   evaluation threw (division by zero, missing field, …)
+   * - `bounds`    exceeded execution limits (AST size, depth, …)
+   * - `dialect`   no engine registered for `expression.dialect`
+   */
+  kind: 'parse' | 'type' | 'runtime' | 'bounds' | 'dialect';
+  message: string;
+  /** Source position when known. */
+  pos?: { start: number; end: number };
+}
+
+/** Contract every dialect engine implements. */
+export interface DialectEngine {
+  /** Dialect identifier — must match `Expression.dialect`. */
+  readonly dialect: string;
+  /**
+   * Parse + type-check + emit AST. Source-only — `expression.ast` is what
+   * actually gets persisted in `objectstack.json`.
+   */
+  compile(source: string): EvalResult<unknown>;
+  /** Evaluate a fully-resolved expression in the given context. */
+  evaluate<T = unknown>(expr: Expression, ctx: EvalContext): EvalResult<T>;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"],
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  }
+}