@dlovans/tenet-core 0.1.4 → 0.2.1

package/README.md

@@ -2,6 +2,8 @@
 
 Declarative logic VM for JSON schemas. Reactive validation, temporal routing, and computed state.
 
+**Pure TypeScript** — No WASM, no native dependencies. Works in browsers, Node.js, Deno, Bun.
+
 ## Installation
 
 ```bash
@@ -13,11 +15,8 @@ npm install @dlovans/tenet-core
 ### Browser
 
 ```html
-<script src="https://unpkg.com/@dlovans/tenet-core/wasm/wasm_exec.js"></script>
 <script type="module">
-import { init, run } from '@dlovans/tenet-core';
-
-await init('/path/to/tenet.wasm');
+import { run } from '@dlovans/tenet-core';
 
 const schema = {
   definitions: {
@@ -33,26 +32,23 @@ const schema = {
 };
 
 const result = run(schema);
-console.log(result);
+console.log(result.result.status); // 'READY'
 </script>
 ```
 
 ### Node.js
 
 ```javascript
-import { init, run, verify } from '@dlovans/tenet-core';
-
-// Initialize WASM
-await init('./node_modules/@dlovans/tenet-core/wasm/tenet.wasm');
+import { run, verify } from '@dlovans/tenet-core';
 
-// Run schema logic
+// Run schema logic - no initialization needed
 const result = run(schema, new Date());
 
 if (result.error) {
   console.error(result.error);
 } else {
   console.log(result.result.status); // 'READY', 'INCOMPLETE', or 'INVALID'
-  console.log(result.result.errors); // Validation errors
+  console.log(result.result.errors); // Validation errors (if any)
 }
 
 // Verify transformation
@@ -62,51 +58,57 @@ console.log(verification.valid);
 
 ## API
 
-### `init(wasmPath?: string): Promise<void>`
-Initialize the WASM module. Must be called before `run()` or `verify()`.
-
 ### `run(schema, date?): TenetResult`
 Execute the schema logic for the given effective date.
 
+- `schema` — TenetSchema object or JSON string
+- `date` — Effective date for temporal routing (default: now)
+
+Returns `{ result: TenetSchema }` or `{ error: string }`.
+
 ### `verify(newSchema, oldSchema): TenetVerifyResult`
 Verify that a transformation is legal by replaying the logic.
 
-### `lint(schema): LintResult` *(No WASM required)*
-Static analysis - find issues without executing the schema.
+Returns `{ valid: boolean, error?: string }`.
 
-```javascript
-import { lint } from '@dlovans/tenet-core';
+### `isReady(): boolean`
+Always returns `true`. Kept for backwards compatibility.
 
-const result = lint(schema);
-// No init() needed - pure TypeScript!
+### `init(): Promise<void>` *(deprecated)*
+No-op. Kept for backwards compatibility with v0.1.x.
 
-if (!result.valid) {
-  for (const issue of result.issues) {
-    console.log(`${issue.severity}: ${issue.message}`);
-  }
-}
-```
+## Runtime Validation
 
-### `isTenetSchema(obj): boolean`
-Check if an object is a Tenet schema.
+The VM automatically detects and reports:
 
-### `isReady(): boolean`
-Check if WASM is initialized.
+- **Undefined variables** — `{"var": "unknown_field"}`
+- **Unknown operators** — `{"invalid_op": [...]}`
+- **Temporal conflicts** — Overlapping date ranges, same start/end dates
 
-## JSON Schema (IDE Support)
+All errors are returned in `result.errors` without failing execution.
 
-Add to your schema files for autocompletion:
+## TypeScript
 
-```json
-{
-  "$schema": "https://tenet.dev/schema/v1.json",
-  "definitions": { ... }
-}
+Full type definitions included:
+
+```typescript
+import type { TenetSchema, TenetResult, Definition, Rule } from '@dlovans/tenet-core';
 ```
 
-## TypeScript
+## Migration from v0.1.x
 
-Full type definitions are included. See `TenetSchema`, `Definition`, `Rule`, `LintResult`, etc.
+```javascript
+// Before (v0.1.x with WASM)
+import { init, run, lint } from '@dlovans/tenet-core';
+await init('./tenet.wasm');
+const result = run(schema);
+const issues = lint(schema);
+
+// After (v0.2.x pure TypeScript)
+import { run } from '@dlovans/tenet-core';
+const result = run(schema);
+// Validation errors are now in result.result.errors
+```
 
 ## License
 

package/dist/core/engine.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Main Tenet VM engine.
+ * Provides run() and verify() functions for schema evaluation.
+ */
+import type { TenetSchema, TenetResult, TenetVerifyResult } from './types.js';
+/**
+ * Run the Tenet VM on a schema.
+ *
+ * @param schema - The schema object
+ * @param effectiveDate - Effective date for temporal routing (defaults to now)
+ * @returns The transformed schema with computed state, errors, and status
+ */
+export declare function run(schema: TenetSchema | string, effectiveDate?: Date | string): TenetResult;
+/**
+ * Verify that a completed document was correctly derived from a base schema.
+ * Simulates the user's journey by iteratively copying visible field values and re-running.
+ *
+ * @param newSchema - The completed/submitted schema
+ * @param oldSchema - The original base schema
+ * @param maxIterations - Maximum replay iterations (default: 100)
+ * @returns Whether the transformation was valid
+ */
+export declare function verify(newSchema: TenetSchema | string, oldSchema: TenetSchema | string, maxIterations?: number): TenetVerifyResult;

package/dist/core/engine.js

@@ -0,0 +1,367 @@
+/**
+ * Main Tenet VM engine.
+ * Provides run() and verify() functions for schema evaluation.
+ */
+import { resolve } from './resolver.js';
+import { isTruthy, toFloat, compareEqual } from './operators.js';
+import { applyTemporalRouting } from './temporal.js';
+import { validateDefinitions, checkAttestations, determineStatus, addError } from './validate.js';
+/**
+ * Infer type string from a value.
+ */
+function inferType(value) {
+    if (typeof value === 'string')
+        return 'string';
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    return 'string'; // default
+}
+/**
+ * Deep clone an object (for immutability).
+ */
+function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+/**
+ * Apply UI modifications to a definition.
+ */
+function applyUIModify(state, key, mods) {
+    const def = state.schema.definitions[key];
+    if (!def) {
+        return;
+    }
+    if (typeof mods !== 'object' || mods === null) {
+        return;
+    }
+    const modMap = mods;
+    // Apply visibility and metadata modifications
+    if (typeof modMap['visible'] === 'boolean') {
+        def.visible = modMap['visible'];
+    }
+    if (typeof modMap['ui_class'] === 'string') {
+        def.ui_class = modMap['ui_class'];
+    }
+    if (typeof modMap['ui_message'] === 'string') {
+        def.ui_message = modMap['ui_message'];
+    }
+    if (typeof modMap['required'] === 'boolean') {
+        def.required = modMap['required'];
+    }
+    // Apply numeric constraints
+    const [minVal, minOk] = toFloat(modMap['min']);
+    if (minOk) {
+        def.min = minVal;
+    }
+    const [maxVal, maxOk] = toFloat(modMap['max']);
+    if (maxOk) {
+        def.max = maxVal;
+    }
+    const [stepVal, stepOk] = toFloat(modMap['step']);
+    if (stepOk) {
+        def.step = stepVal;
+    }
+    // Apply string constraints
+    if (typeof modMap['min_length'] === 'number') {
+        def.min_length = modMap['min_length'];
+    }
+    if (typeof modMap['max_length'] === 'number') {
+        def.max_length = modMap['max_length'];
+    }
+    if (typeof modMap['pattern'] === 'string') {
+        def.pattern = modMap['pattern'];
+    }
+}
+/**
+ * Set a definition value, with cycle detection.
+ */
+function setDefinitionValue(state, key, value, ruleId) {
+    // Cycle detection
+    const prevRule = state.fieldsSet.get(key);
+    if (prevRule && prevRule !== ruleId) {
+        addError(state, key, ruleId, `Potential cycle: field '${key}' set by rule '${prevRule}' and again by rule '${ruleId}'`);
+    }
+    state.fieldsSet.set(key, ruleId);
+    const def = state.schema.definitions[key];
+    if (!def) {
+        // Create new definition if it doesn't exist
+        state.schema.definitions[key] = {
+            type: inferType(value),
+            value,
+            visible: true,
+        };
+        return;
+    }
+    def.value = value;
+}
+/**
+ * Apply a rule's action: setting values, modifying UI, or emitting errors.
+ */
+function applyAction(state, action, ruleId, lawRef) {
+    if (!action) {
+        return;
+    }
+    // Apply value mutations
+    if (action.set) {
+        for (const [key, value] of Object.entries(action.set)) {
+            // Resolve the value in case it's an expression
+            const resolvedValue = resolve(value, state);
+            setDefinitionValue(state, key, resolvedValue, ruleId);
+        }
+    }
+    // Apply UI modifications
+    if (action.ui_modify) {
+        for (const [key, mods] of Object.entries(action.ui_modify)) {
+            applyUIModify(state, key, mods);
+        }
+    }
+    // Emit error if specified
+    if (action.error_msg) {
+        addError(state, '', ruleId, action.error_msg, lawRef);
+    }
+}
+/**
+ * Evaluate the logic tree (all active rules in order).
+ */
+function evaluateLogicTree(state) {
+    if (!state.schema.logic_tree) {
+        return;
+    }
+    for (const rule of state.schema.logic_tree) {
+        if (!rule || rule.disabled) {
+            continue;
+        }
+        // Evaluate the condition
+        const condition = resolve(rule.when, state);
+        if (isTruthy(condition)) {
+            applyAction(state, rule.then, rule.id, rule.law_ref || '');
+        }
+    }
+}
+/**
+ * Compute derived state values.
+ */
+function computeDerived(state) {
+    if (!state.schema.state_model?.derived) {
+        return;
+    }
+    for (const [name, derivedDef] of Object.entries(state.schema.state_model.derived)) {
+        if (!derivedDef?.eval) {
+            continue;
+        }
+        // Evaluate the expression
+        const value = resolve(derivedDef.eval, state);
+        // Store the computed value as a definition (readonly)
+        state.schema.definitions[name] = {
+            type: inferType(value),
+            value,
+            readonly: true,
+            visible: true,
+        };
+    }
+}
+/**
+ * Run the Tenet VM on a schema.
+ *
+ * @param schema - The schema object
+ * @param effectiveDate - Effective date for temporal routing (defaults to now)
+ * @returns The transformed schema with computed state, errors, and status
+ */
+export function run(schema, effectiveDate = new Date()) {
+    try {
+        // Parse if string
+        const parsedSchema = typeof schema === 'string'
+            ? JSON.parse(schema)
+            : deepClone(schema);
+        // Parse date
+        const date = effectiveDate instanceof Date
+            ? effectiveDate
+            : new Date(effectiveDate);
+        // Initialize default visibility for definitions
+        for (const def of Object.values(parsedSchema.definitions)) {
+            if (def && def.visible === undefined) {
+                def.visible = true;
+            }
+        }
+        // Create evaluation state
+        const state = {
+            schema: parsedSchema,
+            effectiveDate: date,
+            fieldsSet: new Map(),
+            errors: [],
+        };
+        // 1. Select temporal branch and prune inactive rules
+        applyTemporalRouting(state);
+        // 2. Compute derived state (so logic tree can use derived values)
+        computeDerived(state);
+        // 3. Evaluate logic tree
+        evaluateLogicTree(state);
+        // 4. Re-compute derived state (in case logic modified inputs)
+        computeDerived(state);
+        // 5. Validate definitions
+        validateDefinitions(state);
+        // 6. Check attestations
+        checkAttestations(state, (action, ruleId, lawRef) => {
+            applyAction(state, action, ruleId, lawRef);
+        });
+        // 7. Determine status and attach errors
+        state.schema.errors = state.errors.length > 0 ? state.errors : undefined;
+        state.schema.status = determineStatus(state);
+        return { result: state.schema };
+    }
+    catch (error) {
+        return { error: String(error) };
+    }
+}
+/**
+ * Get visible, editable fields from a schema.
+ */
+function getVisibleEditableFields(schema) {
+    const result = new Set();
+    for (const [id, def] of Object.entries(schema.definitions)) {
+        if (def && def.visible && !def.readonly) {
+            result.add(id);
+        }
+    }
+    return result;
+}
+/**
+ * Count visible fields in a schema.
+ */
+function countVisibleFields(schema) {
+    let count = 0;
+    for (const def of Object.values(schema.definitions)) {
+        if (def?.visible) {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Validate that the final state matches expected values.
+ */
+function validateFinalState(newSchema, resultSchema) {
+    // Check for unknown/injected fields in newSchema that don't exist in result
+    for (const id of Object.keys(newSchema.definitions)) {
+        if (!(id in resultSchema.definitions)) {
+            return [false, `Unknown field '${id}' not in schema`];
+        }
+    }
+    // Compare computed (readonly) values
+    for (const [id, resultDef] of Object.entries(resultSchema.definitions)) {
+        if (!resultDef?.readonly) {
+            continue;
+        }
+        const newDef = newSchema.definitions[id];
+        if (!newDef) {
+            return [false, `Computed field '${id}' missing in submitted document`];
+        }
+        if (!compareEqual(newDef.value, resultDef.value)) {
+            return [false, `Computed field '${id}' mismatch: claimed ${JSON.stringify(newDef.value)}, expected ${JSON.stringify(resultDef.value)}`];
+        }
+    }
+    // Verify attestations are fulfilled
+    if (resultSchema.attestations) {
+        for (const [id, resultAtt] of Object.entries(resultSchema.attestations)) {
+            if (!resultAtt) {
+                continue;
+            }
+            const newAtt = newSchema.attestations?.[id];
+            if (!newAtt) {
+                continue;
+            }
+            if (resultAtt.required) {
+                if (!newAtt.signed) {
+                    return [false, `Required attestation '${id}' not signed`];
+                }
+                if (!newAtt.evidence?.provider_audit_id) {
+                    return [false, `Attestation '${id}' missing evidence`];
+                }
+                if (!newAtt.evidence?.timestamp) {
+                    return [false, `Attestation '${id}' missing timestamp`];
+                }
+            }
+        }
+    }
+    // Verify status matches
+    if (newSchema.status !== resultSchema.status) {
+        return [false, `Status mismatch: claimed ${newSchema.status}, expected ${resultSchema.status}`];
+    }
+    return [true, undefined];
+}
+/**
+ * Verify that a completed document was correctly derived from a base schema.
+ * Simulates the user's journey by iteratively copying visible field values and re-running.
+ *
+ * @param newSchema - The completed/submitted schema
+ * @param oldSchema - The original base schema
+ * @param maxIterations - Maximum replay iterations (default: 100)
+ * @returns Whether the transformation was valid
+ */
+export function verify(newSchema, oldSchema, maxIterations = 100) {
+    try {
+        // Parse schemas
+        const parsedNewSchema = typeof newSchema === 'string'
+            ? JSON.parse(newSchema)
+            : deepClone(newSchema);
+        const parsedOldSchema = typeof oldSchema === 'string'
+            ? JSON.parse(oldSchema)
+            : deepClone(oldSchema);
+        // Extract effective date from newSchema
+        let effectiveDate = new Date();
+        if (parsedNewSchema.valid_from) {
+            const parsed = new Date(parsedNewSchema.valid_from);
+            if (!isNaN(parsed.getTime())) {
+                effectiveDate = parsed;
+            }
+        }
+        // Start with base schema
+        let currentSchema = parsedOldSchema;
+        let previousVisibleCount = -1;
+        for (let iteration = 0; iteration < maxIterations; iteration++) {
+            // Count visible editable fields before copying
+            const visibleEditable = getVisibleEditableFields(currentSchema);
+            // Copy values from newSchema for visible, editable fields
+            for (const fieldId of visibleEditable) {
+                const newDef = parsedNewSchema.definitions[fieldId];
+                const currentDef = currentSchema.definitions[fieldId];
+                if (newDef && currentDef) {
+                    currentDef.value = newDef.value;
+                }
+            }
+            // Copy attestation states
+            if (currentSchema.attestations) {
+                for (const [attId, currentAtt] of Object.entries(currentSchema.attestations)) {
+                    if (!currentAtt)
+                        continue;
+                    const newAtt = parsedNewSchema.attestations?.[attId];
+                    if (newAtt) {
+                        currentAtt.signed = newAtt.signed;
+                        currentAtt.evidence = newAtt.evidence;
+                    }
+                }
+            }
+            // Run the schema
+            const runResult = run(currentSchema, effectiveDate);
+            if (runResult.error) {
+                return { valid: false, error: `Run failed (iteration ${iteration}): ${runResult.error}` };
+            }
+            const resultSchema = runResult.result;
+            // Count visible fields after run
+            const currentVisibleCount = countVisibleFields(resultSchema);
+            // Check for convergence
+            if (currentVisibleCount === previousVisibleCount) {
+                // Converged - now validate the final state
+                const [valid, error] = validateFinalState(parsedNewSchema, resultSchema);
+                return { valid, error };
+            }
+            previousVisibleCount = currentVisibleCount;
+            currentSchema = resultSchema;
+        }
+        return { valid: false, error: `Verification did not converge after ${maxIterations} iterations` };
+    }
+    catch (error) {
+        return { valid: false, error: String(error) };
+    }
+}

package/dist/core/operators.d.ts

@@ -0,0 +1,30 @@
+/**
+ * JSON-logic operators for the Tenet VM.
+ * All operators are nil-safe: operations on nil/undefined return appropriate defaults.
+ */
+import type { EvalState } from './types.js';
+type ResolveFn = (node: unknown, state: EvalState) => unknown;
+/**
+ * Convert a value to a number if possible.
+ */
+export declare function toFloat(v: unknown): [number, boolean];
+/**
+ * Parse a date value (string or Date).
+ * Supports ISO 8601 formats.
+ */
+export declare function parseDate(v: unknown): [Date, boolean];
+/**
+ * Determine if a value is "truthy" in JSON-logic terms.
+ * nil, false, 0, and "" are falsy. Everything else is truthy.
+ */
+export declare function isTruthy(value: unknown): boolean;
+/**
+ * Compare two values for equality with type coercion.
+ * nil == nil is true, nil == anything_else is false.
+ */
+export declare function compareEqual(a: unknown, b: unknown): boolean;
+/**
+ * Apply an operator to its arguments.
+ */
+export declare function applyOperator(op: string, args: unknown, state: EvalState, resolve: ResolveFn): unknown;
+export {};