@dlovans/tenet-core 0.3.0 → 0.4.0

package/dist/core/lint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Static schema linter for Tenet schemas.
+ * Analyzes schemas without executing them, catching structural errors,
+ * type mismatches, undefined references, and circular dependencies.
+ */
+import type { TenetSchema } from './types.js';
+export type LintSeverity = 'error' | 'warning';
+export interface LintIssue {
+    severity: LintSeverity;
+    code: string;
+    message: string;
+    path?: string;
+    field_id?: string;
+    rule_id?: string;
+}
+export interface LintResult {
+    valid: boolean;
+    issues: LintIssue[];
+}
+export declare function lint(schema: TenetSchema | string): LintResult;

package/dist/core/lint.js

@@ -0,0 +1,622 @@
+/**
+ * Static schema linter for Tenet schemas.
+ * Analyzes schemas without executing them, catching structural errors,
+ * type mismatches, undefined references, and circular dependencies.
+ */
+// ============================================================
+// Constants
+// ============================================================
+const VALID_DEF_TYPES = new Set([
+    'string', 'number', 'boolean', 'select', 'date', 'attestation', 'currency',
+]);
+const SUPPORTED_OPS = new Set([
+    'var', '==', '!=', '>', '<', '>=', '<=',
+    'and', 'or', 'not', '!', 'if',
+    '+', '-', '*', '/',
+    'before', 'after',
+    'in', 'some', 'all', 'none',
+]);
+const ARITHMETIC_OPS = new Set(['+', '-', '*', '/']);
+const COMPARISON_OPS = new Set(['>', '<', '>=', '<=']);
+// ============================================================
+// Helpers
+// ============================================================
+function addIssue(ctx, severity, code, message, opts) {
+    ctx.issues.push({
+        severity,
+        code,
+        message,
+        path: opts?.path,
+        field_id: opts?.field_id,
+        rule_id: opts?.rule_id,
+    });
+}
+function defTypeToInferred(type) {
+    switch (type) {
+        case 'number':
+        case 'currency':
+            return 'number';
+        case 'string':
+        case 'select':
+            return 'string';
+        case 'boolean':
+        case 'attestation':
+            return 'boolean';
+        case 'date':
+            return 'date';
+        default:
+            return 'unknown';
+    }
+}
+// ============================================================
+// Expression type inference
+// ============================================================
+function inferExprType(expr, ctx, path) {
+    if (expr === null || expr === undefined)
+        return 'unknown';
+    if (typeof expr === 'number')
+        return 'number';
+    if (typeof expr === 'string')
+        return 'string';
+    if (typeof expr === 'boolean')
+        return 'boolean';
+    if (Array.isArray(expr))
+        return 'unknown';
+    if (typeof expr !== 'object')
+        return 'unknown';
+    const obj = expr;
+    const keys = Object.keys(obj);
+    if (keys.length !== 1)
+        return 'unknown';
+    const op = keys[0];
+    const args = obj[op];
+    // Check for unknown operators
+    if (!ctx.supportedOps.has(op)) {
+        addIssue(ctx, 'warning', 'unknown_operator', `Unknown operator '${op}'`, { path });
+        return 'unknown';
+    }
+    if (op === 'var') {
+        const varName = typeof args === 'string' ? args : '';
+        const rootName = varName.split('.')[0];
+        const fieldType = ctx.knownFields.get(rootName);
+        if (fieldType !== undefined) {
+            return fieldType;
+        }
+        if (rootName && !ctx.knownFields.has(rootName)) {
+            addIssue(ctx, 'warning', 'undefined_variable', `Variable '${rootName}' is not defined in definitions or derived fields`, {
+                path,
+                field_id: rootName,
+            });
+        }
+        return 'unknown';
+    }
+    if (ARITHMETIC_OPS.has(op)) {
+        const operands = Array.isArray(args) ? args : [args];
+        for (let i = 0; i < operands.length; i++) {
+            const operandType = inferExprType(operands[i], ctx, `${path}.${op}[${i}]`);
+            if (operandType !== 'unknown' && operandType !== 'number') {
+                addIssue(ctx, 'error', 'arithmetic_type_mismatch', `Arithmetic operator '${op}' used with ${operandType} operand (expected number)`, {
+                    path: `${path}.${op}[${i}]`,
+                });
+            }
+        }
+        return 'number';
+    }
+    if (COMPARISON_OPS.has(op)) {
+        const operands = Array.isArray(args) ? args : [args];
+        if (operands.length >= 2) {
+            const leftType = inferExprType(operands[0], ctx, `${path}.${op}[0]`);
+            const rightType = inferExprType(operands[1], ctx, `${path}.${op}[1]`);
+            if (leftType !== 'unknown' && rightType !== 'unknown' && leftType !== rightType) {
+                addIssue(ctx, 'warning', 'comparison_type_mismatch', `Comparison operator '${op}' between ${leftType} and ${rightType}`, {
+                    path,
+                });
+            }
+        }
+        return 'boolean';
+    }
+    if (op === '==' || op === '!=') {
+        // Infer children for side effects (undefined_variable etc) but don't flag type mismatch
+        const operands = Array.isArray(args) ? args : [args];
+        for (let i = 0; i < operands.length; i++) {
+            inferExprType(operands[i], ctx, `${path}.${op}[${i}]`);
+        }
+        return 'boolean';
+    }
+    if (op === 'and' || op === 'or') {
+        const operands = Array.isArray(args) ? args : [args];
+        for (let i = 0; i < operands.length; i++) {
+            inferExprType(operands[i], ctx, `${path}.${op}[${i}]`);
+        }
+        return 'boolean';
+    }
+    if (op === 'not' || op === '!') {
+        inferExprType(args, ctx, `${path}.${op}`);
+        return 'boolean';
+    }
+    if (op === 'if') {
+        const branches = Array.isArray(args) ? args : [];
+        // Walk all branches for side effects
+        for (let i = 0; i < branches.length; i++) {
+            inferExprType(branches[i], ctx, `${path}.if[${i}]`);
+        }
+        // Return type of first then-branch if exists
+        if (branches.length >= 2) {
+            return inferExprType(branches[1], ctx, `${path}.if[1]`);
+        }
+        return 'unknown';
+    }
+    if (op === 'before' || op === 'after') {
+        const operands = Array.isArray(args) ? args : [args];
+        for (let i = 0; i < operands.length; i++) {
+            inferExprType(operands[i], ctx, `${path}.${op}[${i}]`);
+        }
+        return 'boolean';
+    }
+    if (op === 'in' || op === 'some' || op === 'all' || op === 'none') {
+        const operands = Array.isArray(args) ? args : [args];
+        for (let i = 0; i < operands.length; i++) {
+            inferExprType(operands[i], ctx, `${path}.${op}[${i}]`);
+        }
+        return 'boolean';
+    }
+    return 'unknown';
+}
+// ============================================================
+// Var reference extraction (for cycle detection)
+// ============================================================
+function collectVarRefs(node, refs) {
+    if (node === null || node === undefined)
+        return;
+    if (typeof node !== 'object')
+        return;
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            collectVarRefs(item, refs);
+        }
+        return;
+    }
+    const obj = node;
+    const keys = Object.keys(obj);
+    if (keys.length === 1 && keys[0] === 'var') {
+        const varName = typeof obj['var'] === 'string' ? obj['var'] : '';
+        const rootName = varName.split('.')[0];
+        if (rootName)
+            refs.add(rootName);
+        return;
+    }
+    for (const key of keys) {
+        collectVarRefs(obj[key], refs);
+    }
+}
+// ============================================================
+// Check passes
+// ============================================================
+function checkDefinitions(ctx) {
+    const { schema } = ctx;
+    // E1: no definitions
+    if (!schema.definitions || Object.keys(schema.definitions).length === 0) {
+        addIssue(ctx, 'error', 'no_definitions', 'Schema has no definitions');
+        return;
+    }
+    for (const [id, def] of Object.entries(schema.definitions)) {
+        if (!def)
+            continue;
+        // E2: invalid field type
+        if (!VALID_DEF_TYPES.has(def.type)) {
+            addIssue(ctx, 'error', 'invalid_field_type', `Field '${id}' has invalid type '${def.type}'`, { field_id: id });
+        }
+        // E6/E7: select validations
+        if (def.type === 'select') {
+            if (def.options === undefined) {
+                addIssue(ctx, 'error', 'select_missing_options', `Select field '${id}' is missing options`, { field_id: id });
+            }
+            else if (Array.isArray(def.options) && def.options.length === 0) {
+                addIssue(ctx, 'error', 'select_options_empty', `Select field '${id}' has empty options array`, { field_id: id });
+            }
+        }
+        // E8: min > max
+        if (def.min !== undefined && def.max !== undefined && def.min > def.max) {
+            addIssue(ctx, 'error', 'min_exceeds_max', `Field '${id}' has min (${def.min}) greater than max (${def.max})`, { field_id: id });
+        }
+        // E9: min_length > max_length
+        if (def.min_length !== undefined && def.max_length !== undefined && def.min_length > def.max_length) {
+            addIssue(ctx, 'error', 'min_length_exceeds_max_length', `Field '${id}' has min_length (${def.min_length}) greater than max_length (${def.max_length})`, { field_id: id });
+        }
+        // E10: invalid regex
+        if (def.pattern !== undefined) {
+            try {
+                new RegExp(def.pattern);
+            }
+            catch {
+                addIssue(ctx, 'error', 'invalid_regex', `Field '${id}' has invalid regex pattern '${def.pattern}'`, { field_id: id });
+            }
+        }
+        // W22: numeric constraint on non-numeric
+        const inferred = defTypeToInferred(def.type);
+        if ((def.min !== undefined || def.max !== undefined) && inferred !== 'number' && inferred !== 'unknown') {
+            addIssue(ctx, 'warning', 'numeric_constraint_on_non_numeric', `Field '${id}' has min/max constraints but type is '${def.type}'`, { field_id: id });
+        }
+        // W23: string constraint on non-string
+        if ((def.min_length !== undefined || def.max_length !== undefined || def.pattern !== undefined) &&
+            inferred !== 'string' && inferred !== 'unknown') {
+            addIssue(ctx, 'warning', 'string_constraint_on_non_string', `Field '${id}' has string constraints but type is '${def.type}'`, { field_id: id });
+        }
+        // Populate knownFields
+        ctx.knownFields.set(id, defTypeToInferred(def.type));
+    }
+}
+function checkRules(ctx) {
+    const { schema } = ctx;
+    if (!schema.logic_tree || schema.logic_tree.length === 0)
+        return;
+    const seenIds = new Set();
+    for (let i = 0; i < schema.logic_tree.length; i++) {
+        const rule = schema.logic_tree[i];
+        if (!rule)
+            continue;
+        const path = `logic_tree[${i}]`;
+        // E4: empty rule id
+        if (!rule.id || rule.id.trim() === '') {
+            addIssue(ctx, 'error', 'empty_rule_id', `Rule at ${path} has empty or missing id`, { path });
+        }
+        else {
+            // E3: duplicate rule id
+            if (seenIds.has(rule.id)) {
+                addIssue(ctx, 'error', 'duplicate_rule_id', `Duplicate rule id '${rule.id}'`, { path, rule_id: rule.id });
+            }
+            seenIds.add(rule.id);
+        }
+        // E5: missing when/then
+        if (!rule.when || (typeof rule.when === 'object' && Object.keys(rule.when).length === 0)) {
+            addIssue(ctx, 'error', 'rule_missing_when', `Rule '${rule.id || i}' is missing a 'when' condition`, { path, rule_id: rule.id });
+        }
+        if (!rule.then) {
+            addIssue(ctx, 'error', 'rule_missing_then', `Rule '${rule.id || i}' is missing a 'then' action`, { path, rule_id: rule.id });
+        }
+    }
+}
+function checkAttestations(ctx) {
+    const { schema } = ctx;
+    if (!schema.attestations)
+        return;
+    for (const [id, att] of Object.entries(schema.attestations)) {
+        if (!att)
+            continue;
+        // E14: missing statement
+        if (!att.statement || att.statement.trim() === '') {
+            addIssue(ctx, 'error', 'attestation_missing_statement', `Attestation '${id}' is missing a statement`, { field_id: id });
+        }
+    }
+}
+function checkTemporalMap(ctx) {
+    const { schema } = ctx;
+    if (!schema.temporal_map || schema.temporal_map.length === 0)
+        return;
+    for (let i = 0; i < schema.temporal_map.length; i++) {
+        const branch = schema.temporal_map[i];
+        if (!branch)
+            continue;
+        const path = `temporal_map[${i}]`;
+        // E15: missing logic_version
+        if (!branch.logic_version || branch.logic_version.trim() === '') {
+            addIssue(ctx, 'error', 'temporal_branch_missing_version', `Temporal branch at ${path} is missing logic_version`, { path });
+        }
+        // W21: zero-length range
+        const [start, end] = branch.valid_range;
+        if (start && end && start === end) {
+            addIssue(ctx, 'warning', 'temporal_branch_zero_length', `Temporal branch at ${path} has zero-length range (start == end)`, { path });
+        }
+        // W20: overlapping ranges with adjacent branches
+        if (i > 0) {
+            const prev = schema.temporal_map[i - 1];
+            if (prev) {
+                const prevEnd = prev.valid_range[1]
+                    ? new Date(prev.valid_range[1]).getTime()
+                    : Infinity;
+                const currStart = start
+                    ? new Date(start).getTime()
+                    : -Infinity;
+                if (currStart <= prevEnd && !isNaN(prevEnd) && !isNaN(currStart)) {
+                    addIssue(ctx, 'warning', 'temporal_branch_overlap', `Temporal branch ${i} overlaps with branch ${i - 1}`, { path });
+                }
+            }
+        }
+    }
+    // W17: orphaned logic versions (rule versions not in temporal map)
+    if (schema.logic_tree) {
+        const temporalVersions = new Set(schema.temporal_map
+            .filter((b) => !!b)
+            .map(b => b.logic_version));
+        for (let i = 0; i < schema.logic_tree.length; i++) {
+            const rule = schema.logic_tree[i];
+            if (!rule || !rule.logic_version)
+                continue;
+            if (!temporalVersions.has(rule.logic_version)) {
+                addIssue(ctx, 'warning', 'orphaned_logic_version', `Rule '${rule.id}' references logic_version '${rule.logic_version}' which is not in temporal_map`, {
+                    path: `logic_tree[${i}]`,
+                    rule_id: rule.id,
+                });
+            }
+        }
+    }
+}
+function checkDerived(ctx) {
+    const { schema } = ctx;
+    if (!schema.state_model?.derived)
+        return;
+    const derived = schema.state_model.derived;
+    for (const [name, def] of Object.entries(derived)) {
+        if (!def)
+            continue;
+        // E13: missing eval
+        if (!def.eval || (typeof def.eval === 'object' && Object.keys(def.eval).length === 0)) {
+            addIssue(ctx, 'error', 'derived_missing_eval', `Derived field '${name}' has no eval expression`, { field_id: name });
+        }
+    }
+    // W27: inputs reference undefined definitions
+    if (schema.state_model.inputs) {
+        for (const input of schema.state_model.inputs) {
+            if (!ctx.knownFields.has(input)) {
+                addIssue(ctx, 'warning', 'input_references_undefined', `state_model.inputs references undefined field '${input}'`, { field_id: input });
+            }
+        }
+    }
+    // Register derived fields in knownFields (infer type from eval expression)
+    for (const [name, def] of Object.entries(derived)) {
+        if (!def?.eval)
+            continue;
+        // If the derived field already exists as a definition, keep that type
+        if (!ctx.knownFields.has(name)) {
+            const inferredType = inferExprType(def.eval, ctx, `state_model.derived.${name}.eval`);
+            ctx.knownFields.set(name, inferredType);
+        }
+    }
+    // E12: cycle detection via three-color DFS
+    checkDerivedCycles(ctx);
+}
+function checkDerivedCycles(ctx) {
+    const { schema } = ctx;
+    if (!schema.state_model?.derived)
+        return;
+    const derived = schema.state_model.derived;
+    const derivedNames = new Set(Object.keys(derived));
+    // Build adjacency list (only edges to other derived fields)
+    const graph = new Map();
+    for (const [name, def] of Object.entries(derived)) {
+        if (!def?.eval)
+            continue;
+        const refs = new Set();
+        collectVarRefs(def.eval, refs);
+        // Only keep edges to other derived fields
+        const edges = new Set();
+        for (const ref of refs) {
+            if (derivedNames.has(ref) && ref !== name) {
+                edges.add(ref);
+            }
+        }
+        graph.set(name, edges);
+    }
+    // Three-color DFS: 0=white, 1=gray, 2=black
+    const color = new Map();
+    const parent = new Map();
+    for (const name of derivedNames) {
+        color.set(name, 0);
+    }
+    function dfs(node) {
+        color.set(node, 1); // gray
+        const edges = graph.get(node);
+        if (edges) {
+            for (const neighbor of edges) {
+                const neighborColor = color.get(neighbor) ?? 0;
+                if (neighborColor === 1) {
+                    // Found a cycle — reconstruct path
+                    const cycle = [neighbor, node];
+                    let cur = node;
+                    while (cur !== neighbor) {
+                        const p = parent.get(cur);
+                        if (!p || p === neighbor)
+                            break;
+                        cycle.push(p);
+                        cur = p;
+                    }
+                    cycle.reverse();
+                    return cycle;
+                }
+                if (neighborColor === 0) {
+                    parent.set(neighbor, node);
+                    const result = dfs(neighbor);
+                    if (result)
+                        return result;
+                }
+            }
+        }
+        color.set(node, 2); // black
+        return null;
+    }
+    for (const name of derivedNames) {
+        if (color.get(name) === 0) {
+            const cycle = dfs(name);
+            if (cycle) {
+                const cyclePath = cycle.join(' -> ');
+                addIssue(ctx, 'error', 'derived_circular_dependency', `Circular dependency in derived fields: ${cyclePath}`, {
+                    field_id: cycle[0],
+                });
+                return; // Report first cycle only
+            }
+        }
+    }
+}
+function checkExpressions(ctx) {
+    const { schema } = ctx;
+    // Track which fields are set by which rules (for W24)
+    const fieldsSetBy = new Map();
+    if (schema.logic_tree) {
+        for (let i = 0; i < schema.logic_tree.length; i++) {
+            const rule = schema.logic_tree[i];
+            if (!rule)
+                continue;
+            const rulePath = `logic_tree[${i}]`;
+            // Walk the when expression (E11 arithmetic_type_mismatch, W25 comparison, W16 undefined_variable, W28 unknown_operator)
+            if (rule.when) {
+                inferExprType(rule.when, ctx, `${rulePath}.when`);
+            }
+            // Walk the then action
+            if (rule.then) {
+                checkAction(ctx, rule.then, rulePath, rule.id, fieldsSetBy);
+            }
+        }
+    }
+    // W24: multiple rules set the same field
+    for (const [field, ruleIds] of fieldsSetBy) {
+        if (ruleIds.length > 1) {
+            addIssue(ctx, 'warning', 'multiple_rules_set_field', `Field '${field}' is set by multiple rules: ${ruleIds.join(', ')}`, {
+                field_id: field,
+            });
+        }
+    }
+}
+function checkAction(ctx, action, rulePath, ruleId, fieldsSetBy) {
+    if (action.set) {
+        for (const [field, expr] of Object.entries(action.set)) {
+            // W19: set targets a field not in definitions or derived
+            if (!ctx.knownFields.has(field)) {
+                addIssue(ctx, 'warning', 'set_undefined_field', `Rule '${ruleId}' sets undefined field '${field}'`, {
+                    path: `${rulePath}.then.set.${field}`,
+                    field_id: field,
+                    rule_id: ruleId,
+                });
+            }
+            // Track for W24
+            const existing = fieldsSetBy.get(field);
+            if (existing) {
+                existing.push(ruleId);
+            }
+            else {
+                fieldsSetBy.set(field, [ruleId]);
+            }
+            // W26: set type mismatch — infer expression type and compare to field type
+            const exprType = inferExprType(expr, ctx, `${rulePath}.then.set.${field}`);
+            const fieldType = ctx.knownFields.get(field);
+            if (fieldType && fieldType !== 'unknown' && exprType !== 'unknown' && exprType !== fieldType) {
+                addIssue(ctx, 'warning', 'set_type_mismatch', `Rule '${ruleId}' sets '${field}' (${fieldType}) to a ${exprType} expression`, {
+                    path: `${rulePath}.then.set.${field}`,
+                    field_id: field,
+                    rule_id: ruleId,
+                });
+            }
+        }
+    }
+    if (action.ui_modify) {
+        for (const field of Object.keys(action.ui_modify)) {
+            // W18: ui_modify targets undefined field
+            if (!ctx.knownFields.has(field)) {
+                addIssue(ctx, 'warning', 'ui_modify_undefined_field', `Rule '${ruleId}' modifies UI of undefined field '${field}'`, {
+                    path: `${rulePath}.then.ui_modify.${field}`,
+                    field_id: field,
+                    rule_id: ruleId,
+                });
+            }
+        }
+    }
+}
+function checkFieldConflicts(ctx) {
+    // W24 is handled in checkExpressions
+}
+function checkDuplicateIds(ctx) {
+    const { schema } = ctx;
+    // Collect IDs across namespaces
+    const seen = new Map();
+    function track(id, namespace) {
+        const existing = seen.get(id);
+        if (existing) {
+            existing.push(namespace);
+        }
+        else {
+            seen.set(id, [namespace]);
+        }
+    }
+    // Definition keys
+    if (schema.definitions) {
+        for (const id of Object.keys(schema.definitions)) {
+            track(id, 'definition');
+        }
+    }
+    // Rule IDs
+    if (schema.logic_tree) {
+        for (const rule of schema.logic_tree) {
+            if (rule?.id) {
+                track(rule.id, 'rule');
+            }
+        }
+    }
+    // Attestation keys
+    if (schema.attestations) {
+        for (const id of Object.keys(schema.attestations)) {
+            track(id, 'attestation');
+        }
+    }
+    // Derived field keys
+    if (schema.state_model?.derived) {
+        for (const id of Object.keys(schema.state_model.derived)) {
+            track(id, 'derived');
+        }
+    }
+    // Temporal branch logic_versions
+    if (schema.temporal_map) {
+        for (const branch of schema.temporal_map) {
+            if (branch?.logic_version) {
+                track(branch.logic_version, 'temporal_version');
+            }
+        }
+    }
+    // E29: flag any ID appearing in more than one namespace
+    for (const [id, namespaces] of seen) {
+        const unique = [...new Set(namespaces)];
+        if (unique.length > 1) {
+            addIssue(ctx, 'error', 'duplicate_id_across_namespaces', `ID '${id}' appears in multiple namespaces: ${unique.join(', ')}`, {
+                field_id: id,
+            });
+        }
+    }
+}
+// ============================================================
+// Public API
+// ============================================================
+export function lint(schema) {
+    // Parse
+    let parsed;
+    try {
+        parsed = typeof schema === 'string' ? JSON.parse(schema) : schema;
+    }
+    catch (e) {
+        return {
+            valid: false,
+            issues: [{
+                    severity: 'error',
+                    code: 'parse_error',
+                    message: `Failed to parse schema: ${e instanceof Error ? e.message : String(e)}`,
+                }],
+        };
+    }
+    const ctx = {
+        schema: parsed,
+        issues: [],
+        knownFields: new Map(),
+        supportedOps: new Set(SUPPORTED_OPS),
+    };
+    // Run check pipeline in order
+    checkDefinitions(ctx);
+    checkRules(ctx);
+    checkAttestations(ctx);
+    checkTemporalMap(ctx);
+    checkDerived(ctx); // Must run before checkExpressions — updates knownFields for derived
+    checkExpressions(ctx);
+    checkFieldConflicts(ctx);
+    checkDuplicateIds(ctx);
+    const hasErrors = ctx.issues.some(i => i.severity === 'error');
+    return {
+        valid: !hasErrors,
+        issues: ctx.issues,
+    };
+}

package/dist/index.d.ts

@@ -5,7 +5,9 @@
  * Works in both browser and Node.js environments with no WASM dependencies.
  */
 export type { TenetSchema, TenetResult, TenetVerifyResult, VerifyIssue, VerifyIssueCode, Definition, Rule, Action, TemporalBranch, StateModel, DerivedDef, ValidationError, Evidence, Attestation, ErrorKind, } from './core/types.js';
+export type { LintResult, LintIssue, LintSeverity } from './core/lint.js';
 import type { TenetSchema, TenetResult, TenetVerifyResult } from './core/types.js';
+import type { LintResult } from './core/lint.js';
 /**
  * Initialize the Tenet VM.
  * This is a no-op in the pure TypeScript implementation (kept for backwards compatibility).
@@ -30,6 +32,14 @@ export declare function run(schema: TenetSchema | string, date?: Date | string):
  * @returns Whether the transformation is valid
  */
 export declare function verify(newSchema: TenetSchema | string, oldSchema: TenetSchema | string): TenetVerifyResult;
+/**
+ * Lint a schema for structural errors and type mismatches.
+ * Returns issues without executing the schema — pure static analysis.
+ *
+ * @param schema - The schema object or JSON string
+ * @returns Lint result with validity flag and issue list
+ */
+export declare function lint(schema: TenetSchema | string): LintResult;
 /**
  * Check if the VM is ready.
  * Always returns true in the pure TypeScript implementation.

package/dist/index.js

@@ -5,6 +5,7 @@
  * Works in both browser and Node.js environments with no WASM dependencies.
  */
 import { run as coreRun, verify as coreVerify } from './core/engine.js';
+import { lint as coreLint } from './core/lint.js';
 /**
  * Initialize the Tenet VM.
  * This is a no-op in the pure TypeScript implementation (kept for backwards compatibility).
@@ -36,6 +37,16 @@ export function run(schema, date = new Date()) {
 export function verify(newSchema, oldSchema) {
     return coreVerify(newSchema, oldSchema);
 }
+/**
+ * Lint a schema for structural errors and type mismatches.
+ * Returns issues without executing the schema — pure static analysis.
+ *
+ * @param schema - The schema object or JSON string
+ * @returns Lint result with validity flag and issue list
+ */
+export function lint(schema) {
+    return coreLint(schema);
+}
 /**
  * Check if the VM is ready.
  * Always returns true in the pure TypeScript implementation.

package/dist/lint.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for the lint() static schema analyzer.
+ * Organized into: Errors, Warnings, Valid schemas, Edge cases.
+ */
+export {};

package/dist/lint.test.js

@@ -0,0 +1,570 @@
+/**
+ * Tests for the lint() static schema analyzer.
+ * Organized into: Errors, Warnings, Valid schemas, Edge cases.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { lint } from './index.js';
+// Helper: build a minimal valid schema, then override
+function base(overrides) {
+    return {
+        definitions: {
+            name: { type: 'string', value: 'test' },
+        },
+        ...overrides,
+    };
+}
+// Helper: assert a specific issue code exists
+function expectIssue(result, code, severity) {
+    const found = result.issues.find(i => i.code === code && (!severity || i.severity === severity));
+    assert.ok(found, `Expected issue '${code}' (${severity ?? 'any'}) but got: ${JSON.stringify(result.issues.map(i => i.code))}`);
+    return found;
+}
+function expectNoIssue(result, code) {
+    const found = result.issues.find(i => i.code === code);
+    assert.ok(!found, `Did not expect issue '${code}' but found: ${found?.message}`);
+}
+// ===========================================================================
+// Group 1: Errors (valid: false)
+// ===========================================================================
+describe('Lint Errors', () => {
+    it('E1: no_definitions — empty definitions object', () => {
+        const result = lint({ definitions: {} });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'no_definitions', 'error');
+    });
+    it('E2: invalid_field_type — unknown type', () => {
+        const result = lint({
+            definitions: {
+                field1: { type: 'potato', value: 'x' },
+            },
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'invalid_field_type', 'error');
+    });
+    it('E3: duplicate_rule_id — two rules with same id', () => {
+        const result = lint(base({
+            logic_tree: [
+                { id: 'r1', when: { '==': [1, 1] }, then: { set: { name: 'a' } } },
+                { id: 'r1', when: { '==': [2, 2] }, then: { set: { name: 'b' } } },
+            ],
+        }));
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'duplicate_rule_id', 'error');
+    });
+    it('E4: empty_rule_id — rule with empty id', () => {
+        const result = lint(base({
+            logic_tree: [
+                { id: '', when: { '==': [1, 1] }, then: { set: { name: 'a' } } },
+            ],
+        }));
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'empty_rule_id', 'error');
+    });
+    it('E5: rule_missing_when and rule_missing_then', () => {
+        const result = lint(base({
+            logic_tree: [
+                { id: 'r1', when: {}, then: { set: { name: 'a' } } },
+                { id: 'r2', when: { '==': [1, 1] } },
+            ],
+        }));
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'rule_missing_when', 'error');
+        expectIssue(result, 'rule_missing_then', 'error');
+    });
+    it('E6: select_missing_options — select without options', () => {
+        const result = lint({
+            definitions: {
+                color: { type: 'select', value: 'red' },
+            },
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'select_missing_options', 'error');
+    });
+    it('E7: select_options_empty — options is empty array', () => {
+        const result = lint({
+            definitions: {
+                color: { type: 'select', value: 'red', options: [] },
+            },
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'select_options_empty', 'error');
+    });
+    it('E8: min_exceeds_max', () => {
+        const result = lint({
+            definitions: {
+                price: { type: 'number', value: 50, min: 100, max: 50 },
+            },
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'min_exceeds_max', 'error');
+    });
+    it('E9: min_length_exceeds_max_length', () => {
+        const result = lint({
+            definitions: {
+                code: { type: 'string', value: 'abc', min_length: 10, max_length: 5 },
+            },
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'min_length_exceeds_max_length', 'error');
+    });
+    it('E10: invalid_regex', () => {
+        const result = lint({
+            definitions: {
+                code: { type: 'string', value: 'abc', pattern: '[unclosed' },
+            },
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'invalid_regex', 'error');
+    });
+    it('E11: arithmetic_type_mismatch — string + number', () => {
+        const result = lint({
+            definitions: {
+                label: { type: 'string', value: 'hello' },
+                count: { type: 'number', value: 5 },
+            },
+            logic_tree: [
+                {
+                    id: 'r1',
+                    when: { '==': [1, 1] },
+                    then: { set: { result: { '+': [{ var: 'label' }, { var: 'count' }] } } },
+                },
+            ],
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'arithmetic_type_mismatch', 'error');
+    });
+    it('E11b: arithmetic_type_mismatch — boolean * number', () => {
+        const result = lint({
+            definitions: {
+                flag: { type: 'boolean', value: true },
+                amount: { type: 'number', value: 10 },
+            },
+            logic_tree: [
+                {
+                    id: 'r1',
+                    when: { '==': [1, 1] },
+                    then: { set: { result: { '*': [{ var: 'flag' }, 2] } } },
+                },
+            ],
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'arithmetic_type_mismatch', 'error');
+    });
+    it('E12: derived_circular_dependency — A uses B, B uses A', () => {
+        const result = lint({
+            definitions: {
+                input: { type: 'number', value: 1 },
+            },
+            state_model: {
+                inputs: ['input'],
+                derived: {
+                    a: { eval: { '+': [{ var: 'b' }, 1] } },
+                    b: { eval: { '+': [{ var: 'a' }, 1] } },
+                },
+            },
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'derived_circular_dependency', 'error');
+    });
+    it('E13: derived_missing_eval — empty eval', () => {
+        const result = lint({
+            definitions: {
+                input: { type: 'number', value: 1 },
+            },
+            state_model: {
+                inputs: ['input'],
+                derived: {
+                    broken: { eval: {} },
+                },
+            },
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'derived_missing_eval', 'error');
+    });
+    it('E14: attestation_missing_statement', () => {
+        const result = lint(base({
+            attestations: {
+                confirm: { statement: '', required: true },
+            },
+        }));
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'attestation_missing_statement', 'error');
+    });
+    it('E15: temporal_branch_missing_version', () => {
+        const result = lint(base({
+            temporal_map: [
+                { valid_range: ['2025-01-01', '2025-12-31'], logic_version: '', status: 'ACTIVE' },
+            ],
+        }));
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'temporal_branch_missing_version', 'error');
+    });
+    it('E29: duplicate_id_across_namespaces — definition key and derived field key collide', () => {
+        const result = lint({
+            definitions: {
+                total: { type: 'number', value: 100 },
+            },
+            state_model: {
+                inputs: ['total'],
+                derived: {
+                    total: { eval: { '+': [{ var: 'total' }, 1] } },
+                },
+            },
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'duplicate_id_across_namespaces', 'error');
+    });
+});
+// ===========================================================================
+// Group 2: Warnings (valid: true)
+// ===========================================================================
+describe('Lint Warnings', () => {
+    it('W16: undefined_variable — var references ghost field', () => {
+        const result = lint(base({
+            logic_tree: [
+                { id: 'r1', when: { '==': [{ var: 'ghost' }, 1] }, then: { set: { name: 'x' } } },
+            ],
+        }));
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'undefined_variable', 'warning');
+    });
+    it('W17: orphaned_logic_version — rule version not in temporal_map', () => {
+        const result = lint(base({
+            temporal_map: [
+                { valid_range: ['2025-01-01', null], logic_version: 'v1', status: 'ACTIVE' },
+            ],
+            logic_tree: [
+                { id: 'r1', logic_version: 'v2', when: { '==': [1, 1] }, then: { set: { name: 'x' } } },
+            ],
+        }));
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'orphaned_logic_version', 'warning');
+    });
+    it('W18: ui_modify_undefined_field', () => {
+        const result = lint(base({
+            logic_tree: [
+                { id: 'r1', when: { '==': [1, 1] }, then: { ui_modify: { ghost: { visible: false } } } },
+            ],
+        }));
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'ui_modify_undefined_field', 'warning');
+    });
+    it('W19: set_undefined_field', () => {
+        const result = lint(base({
+            logic_tree: [
+                { id: 'r1', when: { '==': [1, 1] }, then: { set: { ghost: 'val' } } },
+            ],
+        }));
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'set_undefined_field', 'warning');
+    });
+    it('W20: temporal_branch_overlap', () => {
+        const result = lint(base({
+            temporal_map: [
+                { valid_range: ['2025-01-01', '2025-06-30'], logic_version: 'v1', status: 'ACTIVE' },
+                { valid_range: ['2025-03-01', '2025-12-31'], logic_version: 'v2', status: 'ACTIVE' },
+            ],
+        }));
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'temporal_branch_overlap', 'warning');
+    });
+    it('W21: temporal_branch_zero_length', () => {
+        const result = lint(base({
+            temporal_map: [
+                { valid_range: ['2025-06-01', '2025-06-01'], logic_version: 'v1', status: 'ACTIVE' },
+            ],
+        }));
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'temporal_branch_zero_length', 'warning');
+    });
+    it('W22: numeric_constraint_on_non_numeric — min on string', () => {
+        const result = lint({
+            definitions: {
+                label: { type: 'string', value: 'hi', min: 5 },
+            },
+        });
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'numeric_constraint_on_non_numeric', 'warning');
+    });
+    it('W23: string_constraint_on_non_string — min_length on number', () => {
+        const result = lint({
+            definitions: {
+                amount: { type: 'number', value: 42, min_length: 3 },
+            },
+        });
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'string_constraint_on_non_string', 'warning');
+    });
+    it('W24: multiple_rules_set_field — two rules set same field', () => {
+        const result = lint({
+            definitions: {
+                price: { type: 'number', value: 10 },
+                flag: { type: 'boolean', value: true },
+            },
+            logic_tree: [
+                { id: 'r1', when: { '==': [{ var: 'flag' }, true] }, then: { set: { price: 20 } } },
+                { id: 'r2', when: { '==': [{ var: 'flag' }, false] }, then: { set: { price: 30 } } },
+            ],
+        });
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'multiple_rules_set_field', 'warning');
+    });
+    it('W25: comparison_type_mismatch — string < number', () => {
+        const result = lint({
+            definitions: {
+                label: { type: 'string', value: 'hi' },
+                count: { type: 'number', value: 5 },
+            },
+            logic_tree: [
+                { id: 'r1', when: { '<': [{ var: 'label' }, { var: 'count' }] }, then: { set: { label: 'low' } } },
+            ],
+        });
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'comparison_type_mismatch', 'warning');
+    });
+    it('W26: set_type_mismatch — arithmetic result assigned to string field', () => {
+        const result = lint({
+            definitions: {
+                label: { type: 'string', value: 'hi' },
+                a: { type: 'number', value: 1 },
+                b: { type: 'number', value: 2 },
+            },
+            logic_tree: [
+                { id: 'r1', when: { '==': [1, 1] }, then: { set: { label: { '+': [{ var: 'a' }, { var: 'b' }] } } } },
+            ],
+        });
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'set_type_mismatch', 'warning');
+    });
+    it('W27: input_references_undefined', () => {
+        const result = lint({
+            definitions: {
+                price: { type: 'number', value: 10 },
+            },
+            state_model: {
+                inputs: ['ghost'],
+                derived: {
+                    doubled: { eval: { '*': [{ var: 'price' }, 2] } },
+                },
+            },
+        });
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'input_references_undefined', 'warning');
+    });
+    it('W28: unknown_operator — unrecognized operator', () => {
+        const result = lint(base({
+            logic_tree: [
+                { id: 'r1', when: { 'modulo': [10, 3] }, then: { set: { name: 'x' } } },
+            ],
+        }));
+        assert.strictEqual(result.valid, true);
+        expectIssue(result, 'unknown_operator', 'warning');
+    });
+});
+// ===========================================================================
+// Group 3: Valid schemas (no issues)
+// ===========================================================================
+describe('Lint Valid Schemas', () => {
+    it('minimal schema — one definition, no rules', () => {
+        const result = lint({
+            definitions: {
+                name: { type: 'string', value: 'test' },
+            },
+        });
+        assert.strictEqual(result.valid, true);
+        assert.strictEqual(result.issues.length, 0);
+    });
+    it('full schema with derived fields, rules, attestations, temporal map', () => {
+        const result = lint({
+            protocol: 'Test_v1',
+            schema_id: 'test-001',
+            definitions: {
+                income: { type: 'number', value: 50000 },
+                deductions: { type: 'number', value: 10000 },
+                status_msg: { type: 'string', value: '' },
+            },
+            state_model: {
+                inputs: ['income', 'deductions'],
+                derived: {
+                    taxable_income: { eval: { '-': [{ var: 'income' }, { var: 'deductions' }] } },
+                },
+            },
+            logic_tree: [
+                {
+                    id: 'high_income',
+                    logic_version: 'v1',
+                    when: { '>': [{ var: 'taxable_income' }, 30000] },
+                    then: { set: { status_msg: 'high bracket' } },
+                },
+            ],
+            temporal_map: [
+                { valid_range: ['2025-01-01', null], logic_version: 'v1', status: 'ACTIVE' },
+            ],
+            attestations: {
+                confirm: { statement: 'I confirm this is correct', required: true },
+            },
+        });
+        assert.strictEqual(result.valid, true);
+        assert.strictEqual(result.issues.length, 0);
+    });
+    it('number + currency arithmetic — compatible types, no error', () => {
+        const result = lint({
+            definitions: {
+                price: { type: 'currency', value: 100 },
+                tax_rate: { type: 'number', value: 0.1 },
+            },
+            state_model: {
+                inputs: ['price', 'tax_rate'],
+                derived: {
+                    tax: { eval: { '*': [{ var: 'price' }, { var: 'tax_rate' }] } },
+                },
+            },
+        });
+        assert.strictEqual(result.valid, true);
+        expectNoIssue(result, 'arithmetic_type_mismatch');
+    });
+});
+// ===========================================================================
+// Group 4: Edge cases
+// ===========================================================================
+describe('Lint Edge Cases', () => {
+    it('JSON string input parses correctly', () => {
+        const json = JSON.stringify({
+            definitions: { x: { type: 'number', value: 1 } },
+        });
+        const result = lint(json);
+        assert.strictEqual(result.valid, true);
+        assert.strictEqual(result.issues.length, 0);
+    });
+    it('invalid JSON string → parse_error', () => {
+        const result = lint('not json {{{');
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'parse_error', 'error');
+    });
+    it('nested expression inference: all-numeric chain produces no error', () => {
+        const result = lint({
+            definitions: {
+                a: { type: 'number', value: 1 },
+                b: { type: 'number', value: 2 },
+                c: { type: 'number', value: 3 },
+            },
+            state_model: {
+                inputs: ['a', 'b', 'c'],
+                derived: {
+                    result: { eval: { '*': [{ '+': [{ var: 'a' }, { var: 'b' }] }, { var: 'c' }] } },
+                },
+            },
+        });
+        assert.strictEqual(result.valid, true);
+        expectNoIssue(result, 'arithmetic_type_mismatch');
+    });
+    it('deep cycle: A→B→C→A', () => {
+        const result = lint({
+            definitions: {
+                input: { type: 'number', value: 1 },
+            },
+            state_model: {
+                inputs: ['input'],
+                derived: {
+                    a: { eval: { '+': [{ var: 'b' }, 1] } },
+                    b: { eval: { '+': [{ var: 'c' }, 1] } },
+                    c: { eval: { '+': [{ var: 'a' }, 1] } },
+                },
+            },
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'derived_circular_dependency', 'error');
+    });
+    it('unknown types do not trigger false errors', () => {
+        // An if-expression returning unknown type used in arithmetic — no error
+        const result = lint({
+            definitions: {
+                flag: { type: 'boolean', value: true },
+                a: { type: 'number', value: 1 },
+            },
+            logic_tree: [
+                {
+                    id: 'r1',
+                    when: { '==': [1, 1] },
+                    then: {
+                        set: {
+                            result: {
+                                '+': [
+                                    { var: 'a' },
+                                    // if-expression: type inferred from first then-branch (number)
+                                    { 'if': [{ var: 'flag' }, 10, 20] },
+                                ],
+                            },
+                        },
+                    },
+                },
+            ],
+        });
+        // The if returns number (inferred from first then-branch=10), so no error
+        expectNoIssue(result, 'arithmetic_type_mismatch');
+    });
+    it('warnings-only → valid: true', () => {
+        const result = lint({
+            definitions: {
+                label: { type: 'string', value: 'hi', min: 5 },
+            },
+        });
+        assert.strictEqual(result.valid, true);
+        assert.ok(result.issues.length > 0, 'Expected at least one warning');
+        assert.ok(result.issues.every(i => i.severity === 'warning'));
+    });
+    it('derived field not in definitions gets registered via inference', () => {
+        const result = lint({
+            definitions: {
+                a: { type: 'number', value: 10 },
+                b: { type: 'number', value: 20 },
+            },
+            state_model: {
+                inputs: ['a', 'b'],
+                derived: {
+                    total: { eval: { '+': [{ var: 'a' }, { var: 'b' }] } },
+                },
+            },
+            logic_tree: [
+                {
+                    id: 'r1',
+                    when: { '>': [{ var: 'total' }, 25] },
+                    then: { set: { a: 0 } },
+                },
+            ],
+        });
+        // 'total' is derived → should be known. No undefined_variable warning.
+        expectNoIssue(result, 'undefined_variable');
+    });
+    it('self-referencing derived field is not flagged as cycle', () => {
+        // self-references are filtered out in cycle detection (ref !== name)
+        const result = lint({
+            definitions: {
+                input: { type: 'number', value: 1 },
+            },
+            state_model: {
+                inputs: ['input'],
+                derived: {
+                    acc: { eval: { '+': [{ var: 'acc' }, { var: 'input' }] } },
+                },
+            },
+        });
+        expectNoIssue(result, 'derived_circular_dependency');
+    });
+    it('E29: rule id collides with attestation key', () => {
+        const result = lint({
+            definitions: {
+                name: { type: 'string', value: 'test' },
+            },
+            logic_tree: [
+                { id: 'confirm', when: { '==': [1, 1] }, then: { set: { name: 'ok' } } },
+            ],
+            attestations: {
+                confirm: { statement: 'I confirm', required: true },
+            },
+        });
+        assert.strictEqual(result.valid, false);
+        expectIssue(result, 'duplicate_id_across_namespaces', 'error');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dlovans/tenet-core",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "type": "module",
     "description": "Declarative logic VM for JSON schemas - reactive validation, temporal routing, and computed state",
     "main": "dist/index.js",