domainforge 0.13.0

package/tests/test_three_valued_eval.py

@@ -0,0 +1,159 @@
+"""
+Test three-valued logic evaluation semantics for policy evaluation.
+
+This test validates that the EvaluationResult correctly handles:
+- True evaluations (policy satisfied)
+- False evaluations (policy violated)
+- Null evaluations (policy evaluation unknown/indeterminate)
+"""
+
+import json
+import pytest
+from domainforge import Graph, EvaluationResult, Severity
+
+
+def test_policy_evaluates_to_true():
+    """Test that a satisfied policy returns is_satisfied=True and tristate=True."""
+    graph = Graph()
+
+    # Create a simple policy that always evaluates to true
+    policy = {
+        "id": "00000000-0000-0000-0000-000000000001",
+        "name": "AlwaysTrue",
+        "namespace": "test",
+        "version": {"major": 1, "minor": 0, "patch": 0},
+        "expression": {"Literal": True},
+        "modality": "Obligation",
+        "kind": "Constraint",
+        "priority": 0,
+        "rationale": None,
+        "tags": [],
+    }
+
+    result = graph.evaluate_policy(json.dumps(policy))
+
+    assert isinstance(result, EvaluationResult)
+    assert result.is_satisfied is True
+    assert result.is_satisfied_tristate is True
+    assert len(result.violations) == 0
+
+
+def test_policy_evaluates_to_false():
+    """Test that a violated policy returns is_satisfied=False and tristate=False."""
+    graph = Graph()
+
+    # Create a simple policy that always evaluates to false
+    policy = {
+        "id": "00000000-0000-0000-0000-000000000002",
+        "name": "AlwaysFalse",
+        "namespace": "test",
+        "version": {"major": 1, "minor": 0, "patch": 0},
+        "expression": {"Literal": False},
+        "modality": "Obligation",
+        "kind": "Constraint",
+        "priority": 0,
+        "rationale": None,
+        "tags": [],
+    }
+
+    result = graph.evaluate_policy(json.dumps(policy))
+
+    assert isinstance(result, EvaluationResult)
+    assert result.is_satisfied is False
+    assert result.is_satisfied_tristate is False
+    assert len(result.violations) == 1
+    assert result.violations[0].name == "AlwaysFalse"
+    assert result.violations[0].severity == Severity.Error
+
+
+def test_policy_evaluates_to_null():
+    """Test that an unknown/null policy evaluation returns is_satisfied=False and tristate=None."""
+    graph = Graph()
+
+    # Create a policy that references a non-existent entity attribute
+    # This should evaluate to NULL when three_valued_logic feature is enabled
+    policy = {
+        "id": "00000000-0000-0000-0000-000000000003",
+        "name": "NullEvaluation",
+        "namespace": "test",
+        "version": {"major": 1, "minor": 0, "patch": 0},
+        "expression": {
+            "MemberAccess": {"object": "NonExistentEntity", "member": "someAttribute"}
+        },
+        "modality": "Obligation",
+        "kind": "Constraint",
+        "priority": 0,
+        "rationale": None,
+        "tags": [],
+    }
+
+    result = graph.evaluate_policy(json.dumps(policy))
+
+    assert isinstance(result, EvaluationResult)
+    # When evaluation is NULL, is_satisfied defaults to False for backwards compatibility
+    assert result.is_satisfied is False
+    # The tristate field should be None to indicate unknown/NULL
+    assert result.is_satisfied_tristate is None
+    # Violation severity follows the policy modality even when evaluation is NULL
+    assert len(result.violations) == 1
+    assert (
+        "UNKNOWN" in result.violations[0].message
+        or "NULL" in result.violations[0].message
+    )
+    assert result.violations[0].severity == Severity.Error
+
+
+def test_evaluation_result_repr():
+    """Test that EvaluationResult has a useful string representation."""
+    graph = Graph()
+
+    policy = {
+        "id": "00000000-0000-0000-0000-000000000004",
+        "name": "TestPolicy",
+        "namespace": "test",
+        "version": {"major": 1, "minor": 0, "patch": 0},
+        "expression": {"Literal": True},
+        "modality": "Obligation",
+        "kind": "Constraint",
+        "priority": 0,
+        "rationale": None,
+        "tags": [],
+    }
+
+    result = graph.evaluate_policy(json.dumps(policy))
+    repr_str = repr(result)
+
+    assert "EvaluationResult" in repr_str
+    assert "is_satisfied" in repr_str
+    assert "violations" in repr_str
+
+
+def test_violation_repr():
+    """Test that Violation has a useful string representation."""
+    graph = Graph()
+
+    policy = {
+        "id": "00000000-0000-0000-0000-000000000005",
+        "name": "ViolatedPolicy",
+        "namespace": "test",
+        "version": {"major": 1, "minor": 0, "patch": 0},
+        "expression": {"Literal": False},
+        "modality": "Prohibition",
+        "kind": "Constraint",
+        "priority": 0,
+        "rationale": None,
+        "tags": [],
+    }
+
+    result = graph.evaluate_policy(json.dumps(policy))
+
+    assert len(result.violations) > 0
+    violation = result.violations[0]
+    repr_str = repr(violation)
+
+    assert "Violation" in repr_str
+    assert "ViolatedPolicy" in repr_str
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": [
+      "ES2020"
+    ],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "types": [
+      "node",
+      "bun-types",
+      "vitest/globals"
+    ]
+  },
+  "include": [
+    "typescript-tests/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

package/typescript-tests/advanced.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'vitest';
+import { Entity, Flow, ResourceInstance, Resource } from '../index';
+
+describe('Instance Advanced Features', () => {
+    it('creates instance with namespace', () => {
+        const entity = new Entity('Warehouse', 'logistics');
+        const resource = new Resource('Camera', 'units', 'inventory');
+
+        const instance = new ResourceInstance(resource.id, entity.id, 'inventory');
+        expect(instance.namespace).toBe('inventory');
+    });
+
+    it('manages instance attributes', () => {
+        const entity = new Entity('Warehouse');
+        const resource = new Resource('Camera', 'units');
+        const instance = new ResourceInstance(resource.id, entity.id);
+
+        instance.setAttribute('serial_number', JSON.stringify('CAM-12345'));
+        expect(JSON.parse(instance.getAttribute('serial_number')!)).toBe('CAM-12345');
+    });
+
+    it('handles complex instance metadata', () => {
+        const entity = new Entity('Warehouse');
+        const resource = new Resource('Camera', 'units');
+        const instance = new ResourceInstance(resource.id, entity.id);
+
+        const metadata = {
+            serial: 'CAM-12345',
+            manufactured: '2025-01-15',
+            warranty_expires: '2027-01-15',
+            specifications: {
+                resolution: '4K',
+                fps: 60
+            }
+        };
+
+        instance.setAttribute('metadata', JSON.stringify(metadata));
+        const retrieved = JSON.parse(instance.getAttribute('metadata')!);
+        expect(retrieved.serial).toBe('CAM-12345');
+        expect(retrieved.specifications.resolution).toBe('4K');
+    });
+});
+
+describe('Attribute Edge Cases', () => {
+    it('handles null attribute retrieval', () => {
+        const entity = new Entity('Test');
+        const attr = entity.getAttribute('nonexistent');
+        expect(attr).toBeNull();
+    });
+
+    it('handles empty string attributes', () => {
+        const entity = new Entity('Test');
+        entity.setAttribute('empty', JSON.stringify(''));
+        expect(JSON.parse(entity.getAttribute('empty')!)).toBe('');
+    });
+
+    it('handles numeric attributes', () => {
+        const resource = new Resource('Item', 'units');
+        resource.setAttribute('quantity', JSON.stringify(42));
+        resource.setAttribute('price', JSON.stringify(99.99));
+
+        expect(JSON.parse(resource.getAttribute('quantity')!)).toBe(42);
+        expect(JSON.parse(resource.getAttribute('price')!)).toBe(99.99);
+    });
+
+    it('handles boolean attributes', () => {
+        const entity = new Entity('Warehouse');
+        entity.setAttribute('active', JSON.stringify(true));
+        entity.setAttribute('requires_signature', JSON.stringify(false));
+
+        expect(JSON.parse(entity.getAttribute('active')!)).toBe(true);
+        expect(JSON.parse(entity.getAttribute('requires_signature')!)).toBe(false);
+    });
+
+    it('handles array attributes', () => {
+        const entity = new Entity('Warehouse');
+        const zones = ['A1', 'A2', 'B1', 'B2'];
+        entity.setAttribute('zones', JSON.stringify(zones));
+
+        const retrieved = JSON.parse(entity.getAttribute('zones')!);
+        expect(retrieved).toEqual(zones);
+        expect(retrieved.length).toBe(4);
+    });
+});
+
+describe('Flow Attributes', () => {
+    it('manages flow attributes', () => {
+        const entity1 = new Entity('Warehouse');
+        const entity2 = new Entity('Factory');
+        const resource = new Resource('Cameras', 'units');
+
+        const flow = new Flow(resource.id, entity1.id, entity2.id, 100);
+        flow.setAttribute('priority', JSON.stringify('high'));
+        flow.setAttribute('scheduled_date', JSON.stringify('2025-12-01'));
+
+        expect(JSON.parse(flow.getAttribute('priority')!)).toBe('high');
+        expect(JSON.parse(flow.getAttribute('scheduled_date')!)).toBe('2025-12-01');
+    });
+
+    it('handles decimal quantities correctly', () => {
+        const entity1 = new Entity('Warehouse');
+        const entity2 = new Entity('Factory');
+        const resource = new Resource('Steel', 'kg');
+
+        const flow = new Flow(resource.id, entity1.id, entity2.id, 1250.75);
+        expect(flow.quantity).toBeCloseTo(1250.75, 2);
+    });
+});
+
+describe('UUID Validation', () => {
+    it('accepts valid UUIDs', () => {
+        const validUuid = '550e8400-e29b-41d4-a716-446655440000';
+        const entity1 = new Entity('Test1');
+        const entity2 = new Entity('Test2');
+
+        // This should not throw
+        expect(() => {
+            new Flow(validUuid, entity1.id, entity2.id, 100);
+        }).not.toThrow();
+    });
+
+    it('rejects malformed UUIDs', () => {
+        expect(() => {
+            new Flow('not-a-uuid', 'also-not', 'still-not', 100);
+        }).toThrow();
+    });
+
+    it('rejects empty string UUIDs', () => {
+        expect(() => {
+            new Flow('', '', '', 100);
+        }).toThrow();
+    });
+});
+
+describe('Namespace Handling', () => {
+    it('entities without namespace have null namespace', () => {
+        const entity = new Entity('Test');
+        expect(entity.namespace).toBeNull();
+    });
+
+    it('entities with namespace preserve it', () => {
+        const entity = new Entity('Test', 'domain');
+        expect(entity.namespace).toBe('domain');
+    });
+
+    it('resources without namespace have null namespace', () => {
+        const resource = new Resource('Item', 'units');
+        expect(resource.namespace).toBeNull();
+    });
+
+    it('resources with namespace preserve it', () => {
+        const resource = new Resource('Item', 'units', 'inventory');
+        expect(resource.namespace).toBe('inventory');
+    });
+
+    it('instances can have different namespace than resource/entity', () => {
+        const entity = new Entity('Warehouse', 'logistics');
+        const resource = new Resource('Camera', 'units', 'inventory');
+        const instance = new ResourceInstance(resource.id, entity.id, 'tracking');
+
+        expect(entity.namespace).toBe('logistics');
+        expect(resource.namespace).toBe('inventory');
+        expect(instance.namespace).toBe('tracking');
+    });
+});

package/typescript-tests/authority.test.ts

@@ -0,0 +1,216 @@
+/**
+ * Tests for the new Policy Authority API exports added in this PR.
+ *
+ * Covers:
+ * - Enum exports: FinalDecision, PolicyModality, SourceClass, ClaimLevel
+ * - Function: evaluateAuthority
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+    FinalDecision,
+    PolicyModality,
+    SourceClass,
+    ClaimLevel,
+    evaluateAuthority,
+} from '../index.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeMinimalConfigJson(packs: unknown[] = []): string {
+    return JSON.stringify({
+        resolver_semantics_version: '0.4',
+        specificity_profile: {
+            id: 'default',
+            dimensions: [],
+            scoring_rules: {},
+            hash: '',
+        },
+        unknown_handling: {
+            permission: { default: 'escalate' },
+            prohibition: { default: 'deny' },
+            obligation: { default: 'escalate' },
+            override_: { default: 'not_applicable' },
+        },
+        fact_sources: [],
+        fact_transforms: [],
+        authority_packs: packs,
+        strict_mode: false,
+        compatibility_lowering_version: '0.4',
+        resolver_version: '0.1',
+    });
+}
+
+function makeMinimalRequestJson(operation = 'TestAction', resourceType = 'Order'): string {
+    return JSON.stringify({
+        request_id: 'req-001',
+        actor: { id: 'user-1' },
+        operation,
+        resource: { type: resourceType },
+        context: {},
+        requested_at: '2026-06-07T00:00:00Z',
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Enum value tests
+// ---------------------------------------------------------------------------
+
+describe('FinalDecision enum', () => {
+    it('exports Allow=0, Deny=1, Escalate=2, NotApplicable=3, Reject=4', () => {
+        expect(FinalDecision.Allow).toBe(0);
+        expect(FinalDecision.Deny).toBe(1);
+        expect(FinalDecision.Escalate).toBe(2);
+        expect(FinalDecision.NotApplicable).toBe(3);
+        expect(FinalDecision.Reject).toBe(4);
+    });
+
+    it('has exactly five members', () => {
+        const keys = Object.keys(FinalDecision).filter((k) => isNaN(Number(k)));
+        expect(keys).toHaveLength(5);
+    });
+});
+
+describe('PolicyModality enum', () => {
+    it('exports Permission=0, Prohibition=1, Obligation=2, Override=3', () => {
+        expect(PolicyModality.Permission).toBe(0);
+        expect(PolicyModality.Prohibition).toBe(1);
+        expect(PolicyModality.Obligation).toBe(2);
+        expect(PolicyModality.Override).toBe(3);
+    });
+
+    it('has exactly four members', () => {
+        const keys = Object.keys(PolicyModality).filter((k) => isNaN(Number(k)));
+        expect(keys).toHaveLength(4);
+    });
+});
+
+describe('SourceClass enum', () => {
+    it('exports all seven source class values', () => {
+        expect(SourceClass.CallerSupplied).toBe(0);
+        expect(SourceClass.RuntimeObserved).toBe(1);
+        expect(SourceClass.SystemOfRecord).toBe(2);
+        expect(SourceClass.Attested).toBe(3);
+        expect(SourceClass.ManualApproval).toBe(4);
+        expect(SourceClass.Derived).toBe(5);
+        expect(SourceClass.UnknownSource).toBe(6);
+    });
+
+    it('has exactly seven members', () => {
+        const keys = Object.keys(SourceClass).filter((k) => isNaN(Number(k)));
+        expect(keys).toHaveLength(7);
+    });
+});
+
+describe('ClaimLevel enum', () => {
+    it('exports AuditBacked=0, Validated=1, FormallyProven=2', () => {
+        expect(ClaimLevel.AuditBacked).toBe(0);
+        expect(ClaimLevel.Validated).toBe(1);
+        expect(ClaimLevel.FormallyProven).toBe(2);
+    });
+
+    it('has exactly three members', () => {
+        const keys = Object.keys(ClaimLevel).filter((k) => isNaN(Number(k)));
+        expect(keys).toHaveLength(3);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// evaluateAuthority
+// ---------------------------------------------------------------------------
+
+describe('evaluateAuthority', () => {
+    it('is a function', () => {
+        expect(typeof evaluateAuthority).toBe('function');
+    });
+
+    it('throws on invalid config JSON', () => {
+        expect(() =>
+            evaluateAuthority('not valid json', makeMinimalRequestJson()),
+        ).toThrow();
+    });
+
+    it('throws on invalid request JSON', () => {
+        expect(() =>
+            evaluateAuthority(makeMinimalConfigJson(), 'not valid json'),
+        ).toThrow();
+    });
+
+    it('throws on invalid facts JSON', () => {
+        expect(() =>
+            evaluateAuthority(makeMinimalConfigJson(), makeMinimalRequestJson(), 'not valid json'),
+        ).toThrow();
+    });
+
+    it('returns an object with traceJson and decisionJson', () => {
+        const result = evaluateAuthority(makeMinimalConfigJson(), makeMinimalRequestJson());
+        expect(result).toHaveProperty('traceJson');
+        expect(result).toHaveProperty('decisionJson');
+        expect(typeof result.traceJson).toBe('string');
+        expect(typeof result.decisionJson).toBe('string');
+    });
+
+    it('traceJson and decisionJson are valid JSON strings', () => {
+        const result = evaluateAuthority(makeMinimalConfigJson(), makeMinimalRequestJson());
+        expect(() => JSON.parse(result.traceJson)).not.toThrow();
+        expect(() => JSON.parse(result.decisionJson)).not.toThrow();
+    });
+
+    it('returns not_applicable when no packs are configured', () => {
+        const result = evaluateAuthority(makeMinimalConfigJson([]), makeMinimalRequestJson());
+        const decision = JSON.parse(result.decisionJson);
+        // With no packs and no applicable policies, expect not_applicable
+        expect(decision).toHaveProperty('final_decision');
+        expect(decision.final_decision).toBe('not_applicable');
+    });
+
+    it('accepts optional facts JSON as a JSON array', () => {
+        const factsJson = JSON.stringify([]);
+        const result = evaluateAuthority(
+            makeMinimalConfigJson(),
+            makeMinimalRequestJson(),
+            factsJson,
+        );
+        expect(result).toHaveProperty('decisionJson');
+    });
+
+    it('decision contains a final_decision field', () => {
+        const result = evaluateAuthority(makeMinimalConfigJson(), makeMinimalRequestJson());
+        const decision = JSON.parse(result.decisionJson);
+        expect(decision).toHaveProperty('final_decision');
+        const validDecisions = ['allow', 'deny', 'escalate', 'not_applicable', 'reject'];
+        expect(validDecisions).toContain(decision.final_decision);
+    });
+
+    it('trace contains request_id matching the request', () => {
+        const result = evaluateAuthority(makeMinimalConfigJson(), makeMinimalRequestJson());
+        const trace = JSON.parse(result.traceJson);
+        // Trace should reference the request_id
+        const traceStr = JSON.stringify(trace);
+        expect(traceStr).toContain('req-001');
+    });
+
+    it('handles different operations in requests', () => {
+        const result1 = evaluateAuthority(
+            makeMinimalConfigJson(),
+            makeMinimalRequestJson('CreateOrder'),
+        );
+        const result2 = evaluateAuthority(
+            makeMinimalConfigJson(),
+            makeMinimalRequestJson('DeleteOrder'),
+        );
+        // Both should return valid results
+        expect(() => JSON.parse(result1.decisionJson)).not.toThrow();
+        expect(() => JSON.parse(result2.decisionJson)).not.toThrow();
+    });
+
+    it('two calls with identical input produce the same final_decision', () => {
+        const config = makeMinimalConfigJson();
+        const request = makeMinimalRequestJson();
+        const r1 = JSON.parse(evaluateAuthority(config, request).decisionJson);
+        const r2 = JSON.parse(evaluateAuthority(config, request).decisionJson);
+        expect(r1.final_decision).toBe(r2.final_decision);
+    });
+});