@arke-institute/rhiza 0.4.1 → 0.5.0

package/dist/__tests__/unit/handoff/recurse.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Recurse Handoff Tests
+ *
+ * Tests for recurse handoff functionality:
+ * - groupOutputsByTarget with recurse ThenSpec
+ * - Route resolution for recurse
+ * - Depth tracking behavior
+ */
+export {};
+//# sourceMappingURL=recurse.test.d.ts.map

package/dist/__tests__/unit/handoff/recurse.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurse.test.d.ts","sourceRoot":"","sources":["../../../../src/__tests__/unit/handoff/recurse.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/__tests__/unit/handoff/recurse.test.js

@@ -0,0 +1,256 @@
+/**
+ * Recurse Handoff Tests
+ *
+ * Tests for recurse handoff functionality:
+ * - groupOutputsByTarget with recurse ThenSpec
+ * - Route resolution for recurse
+ * - Depth tracking behavior
+ */
+import { describe, it, expect } from 'vitest';
+import { groupOutputsByTarget, resolveTarget } from '../../../handoff/target';
+describe('Recurse Handoff', () => {
+    describe('resolveTarget with recurse', () => {
+        it('resolves to default recurse target when no routes', () => {
+            const then = { recurse: 'cluster' };
+            const properties = { entity_id: 'ent_1' };
+            const target = resolveTarget(then, properties);
+            expect(target).toBe('cluster');
+        });
+        it('resolves to route target when route matches', () => {
+            const then = {
+                recurse: 'cluster',
+                route: [
+                    { where: { property: 'should_terminate', equals: true }, target: 'done' },
+                ],
+            };
+            const properties = { entity_id: 'ent_1', should_terminate: true };
+            const target = resolveTarget(then, properties);
+            expect(target).toBe('done');
+        });
+        it('resolves to default when no route matches', () => {
+            const then = {
+                recurse: 'cluster',
+                route: [
+                    { where: { property: 'should_terminate', equals: true }, target: 'done' },
+                ],
+            };
+            const properties = { entity_id: 'ent_1', should_terminate: false };
+            const target = resolveTarget(then, properties);
+            expect(target).toBe('cluster');
+        });
+        it('handles recurse with max_depth (max_depth ignored in routing)', () => {
+            const then = {
+                recurse: 'cluster',
+                max_depth: 10,
+            };
+            const properties = { entity_id: 'ent_1' };
+            // max_depth doesn't affect routing - it's handled in handleRecurse
+            const target = resolveTarget(then, properties);
+            expect(target).toBe('cluster');
+        });
+    });
+    describe('groupOutputsByTarget with recurse', () => {
+        it('groups all outputs to recurse target when no routes', () => {
+            const outputs = ['ent_1', 'ent_2', 'ent_3'];
+            const then = { recurse: 'cluster' };
+            const groups = groupOutputsByTarget(outputs, then);
+            expect(groups.size).toBe(1);
+            expect(groups.get('cluster')).toHaveLength(3);
+            expect(groups.get('cluster')[0].entity_id).toBe('ent_1');
+            expect(groups.get('cluster')[1].entity_id).toBe('ent_2');
+            expect(groups.get('cluster')[2].entity_id).toBe('ent_3');
+        });
+        it('routes items to "done" when condition matches', () => {
+            const outputs = [
+                { entity_id: 'ent_1', is_root: false },
+                { entity_id: 'ent_2', is_root: true },
+                { entity_id: 'ent_3', is_root: false },
+            ];
+            const then = {
+                recurse: 'cluster',
+                route: [
+                    { where: { property: 'is_root', equals: true }, target: 'done' },
+                ],
+            };
+            const groups = groupOutputsByTarget(outputs, then);
+            expect(groups.size).toBe(2);
+            expect(groups.get('cluster')).toHaveLength(2);
+            expect(groups.get('done')).toHaveLength(1);
+            expect(groups.get('done')[0].entity_id).toBe('ent_2');
+        });
+        it('handles all outputs routed to "done" (termination case)', () => {
+            const outputs = [
+                { entity_id: 'ent_1', complete: true },
+                { entity_id: 'ent_2', complete: true },
+            ];
+            const then = {
+                recurse: 'cluster',
+                route: [
+                    { where: { property: 'complete', equals: true }, target: 'done' },
+                ],
+            };
+            const groups = groupOutputsByTarget(outputs, then);
+            expect(groups.size).toBe(1);
+            expect(groups.get('done')).toHaveLength(2);
+            expect(groups.has('cluster')).toBe(false);
+        });
+        it('handles empty outputs (base case)', () => {
+            const outputs = [];
+            const then = { recurse: 'cluster', max_depth: 20 };
+            const groups = groupOutputsByTarget(outputs, then);
+            expect(groups.size).toBe(0);
+        });
+        it('handles complex routing with AND condition', () => {
+            const outputs = [
+                { entity_id: 'ent_1', layer: 3, count: 1 },
+                { entity_id: 'ent_2', layer: 3, count: 5 },
+                { entity_id: 'ent_3', layer: 2, count: 1 },
+            ];
+            const then = {
+                recurse: 'cluster',
+                route: [
+                    {
+                        where: {
+                            and: [
+                                { property: 'layer', equals: 3 },
+                                { property: 'count', equals: 1 },
+                            ],
+                        },
+                        target: 'done',
+                    },
+                ],
+            };
+            const groups = groupOutputsByTarget(outputs, then);
+            expect(groups.size).toBe(2);
+            expect(groups.get('done')).toHaveLength(1);
+            expect(groups.get('done')[0].entity_id).toBe('ent_1');
+            expect(groups.get('cluster')).toHaveLength(2);
+        });
+        it('handles OR condition routing', () => {
+            const outputs = [
+                { entity_id: 'ent_1', status: 'complete' },
+                { entity_id: 'ent_2', status: 'error' },
+                { entity_id: 'ent_3', status: 'pending' },
+            ];
+            const then = {
+                recurse: 'process',
+                route: [
+                    {
+                        where: {
+                            or: [
+                                { property: 'status', equals: 'complete' },
+                                { property: 'status', equals: 'error' },
+                            ],
+                        },
+                        target: 'done',
+                    },
+                ],
+            };
+            const groups = groupOutputsByTarget(outputs, then);
+            expect(groups.get('done')).toHaveLength(2);
+            expect(groups.get('process')).toHaveLength(1);
+            expect(groups.get('process')[0].entity_id).toBe('ent_3');
+        });
+        it('preserves OutputItem properties after grouping', () => {
+            const outputs = [
+                { entity_id: 'ent_1', cluster_id: 'c1', member_count: 5 },
+                { entity_id: 'ent_2', cluster_id: 'c2', member_count: 3 },
+            ];
+            const then = { recurse: 'describe' };
+            const groups = groupOutputsByTarget(outputs, then);
+            const grouped = groups.get('describe');
+            expect(grouped[0]).toEqual({ entity_id: 'ent_1', cluster_id: 'c1', member_count: 5 });
+            expect(grouped[1]).toEqual({ entity_id: 'ent_2', cluster_id: 'c2', member_count: 3 });
+        });
+    });
+    describe('recurse routing scenarios', () => {
+        describe('knowledge graph clustering', () => {
+            it('simulates cluster decision: continue recursion', () => {
+                // Multiple cluster leaders returned -> recurse to describe
+                const outputs = [
+                    { entity_id: 'leader_1', is_leader: true },
+                    { entity_id: 'leader_2', is_leader: true },
+                    { entity_id: 'leader_3', is_leader: true },
+                ];
+                const then = { recurse: 'cluster' };
+                const groups = groupOutputsByTarget(outputs, then);
+                // All should go to cluster (for the next iteration)
+                expect(groups.get('cluster')).toHaveLength(3);
+            });
+            it('simulates cluster decision: single root terminates', () => {
+                // Single output means we've reached the root
+                // In practice, the cluster klados would return empty,
+                // but we can also use routing to terminate
+                const outputs = [
+                    { entity_id: 'root', is_single: true },
+                ];
+                const then = {
+                    recurse: 'cluster',
+                    route: [
+                        { where: { property: 'is_single', equals: true }, target: 'done' },
+                    ],
+                };
+                const groups = groupOutputsByTarget(outputs, then);
+                expect(groups.get('done')).toHaveLength(1);
+                expect(groups.has('cluster')).toBe(false);
+            });
+            it('simulates mixed routing: some done, some continue', () => {
+                // Some entities are already clustered (joiners), others are new leaders
+                const outputs = [
+                    { entity_id: 'leader_1', action: 'created_leader' },
+                    { entity_id: 'joiner_1', action: 'joined_existing' },
+                    { entity_id: 'leader_2', action: 'created_leader' },
+                    { entity_id: 'joiner_2', action: 'joined_existing' },
+                ];
+                const then = {
+                    recurse: 'describe',
+                    route: [
+                        { where: { property: 'action', equals: 'joined_existing' }, target: 'done' },
+                    ],
+                };
+                const groups = groupOutputsByTarget(outputs, then);
+                expect(groups.get('describe')).toHaveLength(2);
+                expect(groups.get('done')).toHaveLength(2);
+            });
+        });
+        describe('iterative processing', () => {
+            it('routes based on iteration depth property', () => {
+                // Items carry their own depth tracking
+                const outputs = [
+                    { entity_id: 'item_1', iteration: 1 },
+                    { entity_id: 'item_2', iteration: 5 },
+                    { entity_id: 'item_3', iteration: 10 },
+                ];
+                const then = {
+                    recurse: 'process',
+                    max_depth: 100,
+                    route: [
+                        { where: { property: 'iteration', equals: 10 }, target: 'done' },
+                    ],
+                };
+                const groups = groupOutputsByTarget(outputs, then);
+                expect(groups.get('process')).toHaveLength(2);
+                expect(groups.get('done')).toHaveLength(1);
+                expect(groups.get('done')[0].entity_id).toBe('item_3');
+            });
+            it('handles convergence check routing', () => {
+                // Items with no change should terminate
+                const outputs = [
+                    { entity_id: 'item_1', changed: true },
+                    { entity_id: 'item_2', changed: false },
+                    { entity_id: 'item_3', changed: true },
+                ];
+                const then = {
+                    recurse: 'refine',
+                    route: [
+                        { where: { property: 'changed', equals: false }, target: 'done' },
+                    ],
+                };
+                const groups = groupOutputsByTarget(outputs, then);
+                expect(groups.get('refine')).toHaveLength(2);
+                expect(groups.get('done')).toHaveLength(1);
+            });
+        });
+    });
+});
+//# sourceMappingURL=recurse.test.js.map

package/dist/__tests__/unit/handoff/recurse.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurse.test.js","sourceRoot":"","sources":["../../../../src/__tests__/unit/handoff/recurse.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/unit/validation/rhiza.test.js

@@ -20,7 +20,7 @@
  * - ThenSpec targets are step names (strings)
  */
 import { describe, it, expect } from 'vitest';
-import { validateRhizaProperties } from '../../../validation';
+import { validateRhizaProperties, validateRhizaUpdate } from '../../../validation';
 import { ref } from '../../../types';
 import { linearRhizaProperties, scatterGatherRhizaProperties, conditionalRhizaProperties, complexRoutingRhizaProperties, invalidRhizaProperties, } from '../../fixtures';
 describe('validateRhizaProperties', () => {
@@ -212,6 +212,52 @@ describe('validateRhizaProperties', () => {
             const cycleError = result.errors.find((e) => e.code === 'CYCLE_DETECTED');
             expect(cycleError?.message).toContain('->');
         });
+        it('does NOT flag recurse as a cycle (recurse is allowed)', () => {
+            const result = validateRhizaProperties({
+                label: 'Recurse Loop',
+                version: '1.0.0',
+                entry: 'step_a',
+                flow: {
+                    'step_a': { klados: ref('II01klados_a', { type: 'klados' }), then: { pass: 'step_b' } },
+                    'step_b': { klados: ref('II01klados_b', { type: 'klados' }), then: { recurse: 'step_a' } },
+                },
+                status: 'active',
+            });
+            // Recurse should NOT be flagged as a cycle
+            expect(result.valid).toBe(true);
+            expect(result.errors.filter(e => e.code === 'CYCLE_DETECTED')).toHaveLength(0);
+        });
+        it('does NOT flag recurse self-reference as a cycle', () => {
+            const result = validateRhizaProperties({
+                label: 'Self Recurse',
+                version: '1.0.0',
+                entry: 'step_a',
+                flow: {
+                    'step_a': { klados: ref('II01klados_a', { type: 'klados' }), then: { recurse: 'step_a' } },
+                },
+                status: 'active',
+            });
+            // Recurse to self should be valid (bounded by max_depth)
+            expect(result.valid).toBe(true);
+            expect(result.errors.filter(e => e.code === 'CYCLE_DETECTED')).toHaveLength(0);
+        });
+        it('still flags regular pass cycles even when recurse is present elsewhere', () => {
+            const result = validateRhizaProperties({
+                label: 'Mixed Cycles',
+                version: '1.0.0',
+                entry: 'step_a',
+                flow: {
+                    'step_a': { klados: ref('II01klados_a', { type: 'klados' }), then: { pass: 'step_b' } },
+                    'step_b': { klados: ref('II01klados_b', { type: 'klados' }), then: { pass: 'step_c' } },
+                    'step_c': { klados: ref('II01klados_c', { type: 'klados' }), then: { pass: 'step_a' } }, // Regular cycle - should fail
+                },
+                status: 'active',
+            });
+            expect(result.valid).toBe(false);
+            expect(result.errors).toContainEqual(expect.objectContaining({
+                code: 'CYCLE_DETECTED',
+            }));
+        });
     });
     // =========================================================================
     // Unreachable Detection
@@ -310,6 +356,118 @@ describe('validateRhizaProperties', () => {
             });
             expect(result.valid).toBe(true);
         });
+        it('accepts recurse handoff', () => {
+            const result = validateRhizaProperties({
+                label: 'Recurse Test',
+                version: '1.0.0',
+                entry: 'step_a',
+                flow: {
+                    'step_a': { klados: ref('II01klados_a', { type: 'klados' }), then: { pass: 'step_b' } },
+                    'step_b': { klados: ref('II01klados_b', { type: 'klados' }), then: { recurse: 'step_a' } },
+                },
+                status: 'active',
+            });
+            expect(result.valid).toBe(true);
+        });
+        it('accepts recurse handoff with max_depth', () => {
+            const result = validateRhizaProperties({
+                label: 'Recurse with Depth',
+                version: '1.0.0',
+                entry: 'step_a',
+                flow: {
+                    'step_a': { klados: ref('II01klados_a', { type: 'klados' }), then: { pass: 'step_b' } },
+                    'step_b': { klados: ref('II01klados_b', { type: 'klados' }), then: { recurse: 'step_a', max_depth: 20 } },
+                },
+                status: 'active',
+            });
+            expect(result.valid).toBe(true);
+        });
+        it('fails when recurse max_depth is negative', () => {
+            const result = validateRhizaProperties({
+                label: 'Invalid Max Depth',
+                version: '1.0.0',
+                entry: 'step_a',
+                flow: {
+                    'step_a': { klados: ref('II01klados_a', { type: 'klados' }), then: { pass: 'step_b' } },
+                    'step_b': { klados: ref('II01klados_b', { type: 'klados' }), then: { recurse: 'step_a', max_depth: -1 } },
+                },
+                status: 'active',
+            });
+            expect(result.valid).toBe(false);
+            expect(result.errors).toContainEqual(expect.objectContaining({
+                code: 'INVALID_MAX_DEPTH',
+            }));
+        });
+        it('fails when recurse max_depth is zero', () => {
+            const result = validateRhizaProperties({
+                label: 'Zero Max Depth',
+                version: '1.0.0',
+                entry: 'step_a',
+                flow: {
+                    'step_a': { klados: ref('II01klados_a', { type: 'klados' }), then: { pass: 'step_b' } },
+                    'step_b': { klados: ref('II01klados_b', { type: 'klados' }), then: { recurse: 'step_a', max_depth: 0 } },
+                },
+                status: 'active',
+            });
+            expect(result.valid).toBe(false);
+            expect(result.errors).toContainEqual(expect.objectContaining({
+                code: 'INVALID_MAX_DEPTH',
+            }));
+        });
+        it('fails when recurse max_depth is not an integer', () => {
+            const result = validateRhizaProperties({
+                label: 'Float Max Depth',
+                version: '1.0.0',
+                entry: 'step_a',
+                flow: {
+                    'step_a': { klados: ref('II01klados_a', { type: 'klados' }), then: { pass: 'step_b' } },
+                    'step_b': { klados: ref('II01klados_b', { type: 'klados' }), then: { recurse: 'step_a', max_depth: 10.5 } },
+                },
+                status: 'active',
+            });
+            expect(result.valid).toBe(false);
+            expect(result.errors).toContainEqual(expect.objectContaining({
+                code: 'INVALID_MAX_DEPTH',
+            }));
+        });
+        it('fails when recurse target does not exist', () => {
+            const result = validateRhizaProperties({
+                label: 'Invalid Recurse Target',
+                version: '1.0.0',
+                entry: 'step_a',
+                flow: {
+                    'step_a': { klados: ref('II01klados_a', { type: 'klados' }), then: { pass: 'step_b' } },
+                    'step_b': { klados: ref('II01klados_b', { type: 'klados' }), then: { recurse: 'nonexistent' } },
+                },
+                status: 'active',
+            });
+            expect(result.valid).toBe(false);
+            expect(result.errors).toContainEqual(expect.objectContaining({
+                code: 'INVALID_TARGET',
+            }));
+        });
+        it('accepts recurse with route rules', () => {
+            const result = validateRhizaProperties({
+                label: 'Recurse with Routes',
+                version: '1.0.0',
+                entry: 'step_a',
+                flow: {
+                    'step_a': { klados: ref('II01klados_a', { type: 'klados' }), then: { pass: 'step_b' } },
+                    'step_b': {
+                        klados: ref('II01klados_b', { type: 'klados' }),
+                        then: {
+                            recurse: 'step_a',
+                            max_depth: 10,
+                            route: [
+                                { where: { property: 'should_terminate', equals: true }, target: 'done' },
+                            ],
+                        },
+                    },
+                },
+                status: 'active',
+            });
+            expect(result.valid).toBe(true);
+        });
     });
     // =========================================================================
     // Route Rules Validation
@@ -639,4 +797,111 @@ describe('validateRhizaProperties', () => {
         });
     });
 });
+// =========================================================================
+// validateRhizaUpdate Tests
+// =========================================================================
+describe('validateRhizaUpdate', () => {
+    const existingProperties = {
+        label: 'Original Workflow',
+        version: '1.0.0',
+        entry: 'step_a',
+        flow: {
+            'step_a': { klados: ref('II01klados_a', { type: 'klados' }), then: { pass: 'step_b' } },
+            'step_b': { klados: ref('II01klados_b', { type: 'klados' }), then: { done: true } },
+        },
+        status: 'active',
+    };
+    it('skips validation when updating label only (no structural changes)', () => {
+        const update = { label: 'Updated Workflow' };
+        const result = validateRhizaUpdate(update, existingProperties);
+        // When neither entry nor flow is being updated, validation is skipped
+        expect(result.valid).toBe(true);
+        expect(result.errors).toHaveLength(0);
+        expect(result.warnings).toHaveLength(0);
+    });
+    it('skips validation when updating version only (no structural changes)', () => {
+        const update = { version: '2.0.0' };
+        const result = validateRhizaUpdate(update, existingProperties);
+        // When neither entry nor flow is being updated, validation is skipped
+        expect(result.valid).toBe(true);
+        expect(result.errors).toHaveLength(0);
+        expect(result.warnings).toHaveLength(0);
+    });
+    it('skips validation when update is empty', () => {
+        const update = {};
+        const result = validateRhizaUpdate(update, existingProperties);
+        // When neither entry nor flow is being updated, validation is skipped
+        expect(result.valid).toBe(true);
+        expect(result.errors).toHaveLength(0);
+    });
+    it('validates merged properties when changing entry', () => {
+        const update = { entry: 'step_b' };
+        const result = validateRhizaUpdate(update, existingProperties);
+        expect(result.valid).toBe(true);
+        expect(result.errors).toHaveLength(0);
+    });
+    it('fails when changing entry to non-existent step', () => {
+        const update = { entry: 'nonexistent' };
+        const result = validateRhizaUpdate(update, existingProperties);
+        expect(result.valid).toBe(false);
+        expect(result.errors).toContainEqual(expect.objectContaining({
+            code: 'ENTRY_NOT_IN_FLOW',
+        }));
+    });
+    it('merges flow at step level when updating flow', () => {
+        // Add a new step to the existing flow
+        const update = {
+            flow: {
+                'step_c': { klados: ref('II01klados_c', { type: 'klados' }), then: { done: true } },
+            },
+        };
+        const result = validateRhizaUpdate(update, existingProperties);
+        // Should be valid - the new step is added but also existing steps remain
+        expect(result.valid).toBe(true);
+    });
+    it('can update an existing step in flow', () => {
+        // Change step_b to point somewhere else
+        const update = {
+            flow: {
+                'step_b': { klados: ref('II01klados_b_updated', { type: 'klados' }), then: { pass: 'step_c' } },
+                'step_c': { klados: ref('II01klados_c', { type: 'klados' }), then: { done: true } },
+            },
+        };
+        const result = validateRhizaUpdate(update, existingProperties);
+        expect(result.valid).toBe(true);
+    });
+    it('fails when update introduces invalid target', () => {
+        const update = {
+            flow: {
+                'step_b': { klados: ref('II01klados_b', { type: 'klados' }), then: { pass: 'nonexistent' } },
+            },
+        };
+        const result = validateRhizaUpdate(update, existingProperties);
+        expect(result.valid).toBe(false);
+        expect(result.errors).toContainEqual(expect.objectContaining({
+            code: 'INVALID_TARGET',
+        }));
+    });
+    it('fails when update introduces a cycle', () => {
+        const update = {
+            flow: {
+                'step_b': { klados: ref('II01klados_b', { type: 'klados' }), then: { pass: 'step_a' } },
+            },
+        };
+        const result = validateRhizaUpdate(update, existingProperties);
+        expect(result.valid).toBe(false);
+        expect(result.errors).toContainEqual(expect.objectContaining({
+            code: 'CYCLE_DETECTED',
+        }));
+    });
+    it('succeeds when update introduces recurse (not a cycle)', () => {
+        const update = {
+            flow: {
+                'step_b': { klados: ref('II01klados_b', { type: 'klados' }), then: { recurse: 'step_a', max_depth: 10 } },
+            },
+        };
+        const result = validateRhizaUpdate(update, existingProperties);
+        expect(result.valid).toBe(true);
+    });
+});
 //# sourceMappingURL=rhiza.test.js.map