@plures/praxis 1.1.3 → 1.2.10

package/src/decision-ledger/types.ts

@@ -0,0 +1,247 @@
+/**
+ * Decision Ledger - Contract Types
+ *
+ * Types for defining and validating contracts for rules and constraints.
+ * All types are JSON-serializable for cross-language compatibility.
+ */
+
+/**
+ * A single assumption made during contract definition.
+ */
+export interface Assumption {
+  /** Stable unique identifier for the assumption */
+  id: string;
+  /** The assumption statement */
+  statement: string;
+  /** Confidence level (0.0 to 1.0) */
+  confidence: number;
+  /** Justification for the assumption */
+  justification: string;
+  /** What this assumption was derived from */
+  derivedFrom?: string;
+  /** What artifacts this assumption impacts */
+  impacts: Array<'spec' | 'tests' | 'code'>;
+  /** Current status of the assumption */
+  status: 'active' | 'revised' | 'invalidated';
+}
+
+/**
+ * A reference to external documentation or resources.
+ */
+export interface Reference {
+  /** Type of reference (e.g., 'doc', 'ticket', 'issue') */
+  type: string;
+  /** URL to the reference */
+  url?: string;
+  /** Human-readable description */
+  description?: string;
+}
+
+/**
+ * A Given/When/Then example for a contract.
+ */
+export interface Example {
+  /** Initial state or preconditions */
+  given: string;
+  /** Triggering event or action */
+  when: string;
+  /** Expected outcome or postconditions */
+  then: string;
+}
+
+/**
+ * Contract for a rule or constraint.
+ * Documents the expected behavior, test cases, invariants, and assumptions.
+ */
+export interface Contract {
+  /** ID of the rule or constraint this contract applies to */
+  ruleId: string;
+  /** Canonical behavior description */
+  behavior: string;
+  /** Given/When/Then examples (become test vectors) */
+  examples: Example[];
+  /** TLA+-friendly invariants or Praxis-level invariants */
+  invariants: string[];
+  /** Explicit assumptions with confidence levels */
+  assumptions?: Assumption[];
+  /** References to docs, tickets, links */
+  references?: Reference[];
+  /** Contract version (for evolution tracking) */
+  version?: string;
+  /** Timestamp of contract creation */
+  timestamp?: string;
+}
+
+/**
+ * Type guard to check if an object is a valid Contract.
+ */
+export function isContract(obj: unknown): obj is Contract {
+  if (typeof obj !== 'object' || obj === null) {
+    return false;
+  }
+
+  const contract = obj as Partial<Contract>;
+
+  return (
+    typeof contract.ruleId === 'string' &&
+    typeof contract.behavior === 'string' &&
+    Array.isArray(contract.examples) &&
+    contract.examples.length > 0 &&
+    contract.examples.every(
+      (ex) =>
+        typeof ex === 'object' &&
+        ex !== null &&
+        typeof ex.given === 'string' &&
+        typeof ex.when === 'string' &&
+        typeof ex.then === 'string'
+    ) &&
+    Array.isArray(contract.invariants) &&
+    contract.invariants.every((inv) => typeof inv === 'string')
+  );
+}
+
+/**
+ * Options for defining a contract.
+ */
+export interface DefineContractOptions {
+  /** ID of the rule or constraint */
+  ruleId: string;
+  /** Canonical behavior description */
+  behavior: string;
+  /** Given/When/Then examples */
+  examples: Example[];
+  /** Invariants that must hold */
+  invariants: string[];
+  /** Optional assumptions */
+  assumptions?: Assumption[];
+  /** Optional references */
+  references?: Reference[];
+  /** Optional version */
+  version?: string;
+}
+
+/**
+ * Define a contract for a rule or constraint.
+ *
+ * @example
+ * const loginContract = defineContract({
+ *   ruleId: 'auth.login',
+ *   behavior: 'Process login events and create user session facts',
+ *   examples: [
+ *     {
+ *       given: 'User provides valid credentials',
+ *       when: 'LOGIN event is received',
+ *       then: 'UserSessionCreated fact is emitted'
+ *     }
+ *   ],
+ *   invariants: ['Session must have unique ID']
+ * });
+ */
+export function defineContract(options: DefineContractOptions): Contract {
+  if (options.examples.length === 0) {
+    throw new Error('Contract must have at least one example');
+  }
+
+  // Validate assumption confidence values are in range [0.0, 1.0]
+  if (options.assumptions) {
+    for (const assumption of options.assumptions) {
+      if (assumption.confidence < 0.0 || assumption.confidence > 1.0) {
+        throw new Error(
+          `Assumption '${assumption.id}' has invalid confidence value ${assumption.confidence}. Must be between 0.0 and 1.0`
+        );
+      }
+    }
+  }
+
+  return {
+    ruleId: options.ruleId,
+    behavior: options.behavior,
+    examples: options.examples,
+    invariants: options.invariants,
+    assumptions: options.assumptions,
+    references: options.references,
+    version: options.version || '1.0.0',
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Extract contract from rule/constraint metadata.
+ */
+export function getContract(meta?: Record<string, unknown>): Contract | undefined {
+  if (!meta || !meta.contract) {
+    return undefined;
+  }
+
+  if (isContract(meta.contract)) {
+    return meta.contract;
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract contract from a rule or constraint descriptor.
+ */
+export function getContractFromDescriptor(descriptor?: {
+  contract?: Contract;
+  meta?: Record<string, unknown>;
+}): Contract | undefined {
+  if (!descriptor) {
+    return undefined;
+  }
+
+  if (descriptor.contract && isContract(descriptor.contract)) {
+    return descriptor.contract;
+  }
+
+  return getContract(descriptor.meta);
+}
+
+/**
+ * Severity levels for contract gaps.
+ */
+export type Severity = 'warning' | 'error' | 'info';
+
+/**
+ * Types of missing contract artifacts.
+ */
+/**
+ * Types of artifacts that can be missing from a contract.
+ * 
+ * Note: 'tests' and 'spec' are included in this type for future extensibility
+ * and SARIF reporting compatibility, but are not currently validated by the
+ * validateContract function. To check for these, implement custom validation
+ * logic that scans for test files or spec files in your codebase.
+ */
+export type MissingArtifact = 'behavior' | 'examples' | 'invariants' | 'tests' | 'spec' | 'contract';
+
+/**
+ * A gap in contract coverage.
+ */
+export interface ContractGap {
+  /** ID of the rule or constraint */
+  ruleId: string;
+  /** What is missing */
+  missing: MissingArtifact[];
+  /** Severity of the gap */
+  severity: Severity;
+  /** Optional human-readable message */
+  message?: string;
+}
+
+/**
+ * Result of contract validation.
+ */
+export interface ValidationReport {
+  /** Rules/constraints with complete contracts */
+  complete: Array<{ ruleId: string; contract: Contract }>;
+  /** Rules/constraints with incomplete contracts */
+  incomplete: ContractGap[];
+  /** Rules/constraints with no contract at all */
+  missing: string[];
+  /** Total number of rules/constraints validated */
+  total: number;
+  /** Timestamp of validation */
+  timestamp: string;
+}

package/src/decision-ledger/validation.ts

@@ -0,0 +1,336 @@
+/**
+ * Decision Ledger - Validation
+ *
+ * Contract validation logic for rules and constraints.
+ */
+
+import type { PraxisRegistry } from '../core/rules.js';
+import type {
+  Contract,
+  ContractGap,
+  ValidationReport,
+  MissingArtifact,
+  Severity,
+} from './types.js';
+import { getContractFromDescriptor } from './types.js';
+
+/**
+ * Options for contract validation.
+ */
+export interface ValidateOptions {
+  /** Treat missing contracts as errors instead of warnings */
+  strict?: boolean;
+  /** Severity for missing contracts (default: 'warning') */
+  missingSeverity?: Severity;
+  /** Severity for incomplete contracts (default: 'warning') */
+  incompleteSeverity?: Severity;
+  /** Required contract fields */
+  requiredFields?: Array<'behavior' | 'examples' | 'invariants'>;
+  /** Optional index of artifacts for test/spec presence */
+  artifactIndex?: ArtifactIndex;
+}
+
+/**
+ * Artifact index for contract compliance checks.
+ */
+export interface ArtifactIndex {
+  /** Rule IDs that have associated tests */
+  tests?: Set<string>;
+  /** Rule IDs that have associated specs (e.g., TLA+) */
+  spec?: Set<string>;
+  /** Optional mapping of rule IDs to contract versions (for drift detection) */
+  contractVersions?: Map<string, string>;
+}
+
+/**
+ * Validate contracts in a registry.
+ *
+ * @param registry The registry to validate
+ * @param options Validation options
+ * @returns Validation report
+ */
+export function validateContracts<TContext = unknown>(
+  registry: PraxisRegistry<TContext>,
+  options: ValidateOptions = {}
+): ValidationReport {
+  const {
+    incompleteSeverity = 'warning',
+    requiredFields = ['behavior', 'examples'],
+    artifactIndex,
+  } = options;
+
+  const complete: Array<{ ruleId: string; contract: Contract }> = [];
+  const incomplete: ContractGap[] = [];
+  const missing: string[] = [];
+
+  // Validate rules
+  for (const rule of registry.getAllRules()) {
+    const contract = getContractFromDescriptor(rule);
+
+    if (!contract) {
+      missing.push(rule.id);
+      if (options.missingSeverity) {
+        incomplete.push({
+          ruleId: rule.id,
+          missing: ['contract'],
+          severity: options.missingSeverity,
+          message: `Rule '${rule.id}' has no contract`,
+        });
+      }
+      continue;
+    }
+
+    const gaps = validateContract(contract, requiredFields, artifactIndex);
+
+    if (gaps.length > 0) {
+      incomplete.push({
+        ruleId: rule.id,
+        missing: gaps,
+        severity: incompleteSeverity,
+        message: `Rule '${rule.id}' contract is incomplete: missing ${gaps.join(', ')}`,
+      });
+    } else {
+      complete.push({ ruleId: rule.id, contract });
+    }
+  }
+
+  // Validate constraints
+  for (const constraint of registry.getAllConstraints()) {
+    const contract = getContractFromDescriptor(constraint);
+
+    if (!contract) {
+      missing.push(constraint.id);
+      if (options.missingSeverity) {
+        incomplete.push({
+          ruleId: constraint.id,
+          missing: ['contract'],
+          severity: options.missingSeverity,
+          message: `Constraint '${constraint.id}' has no contract`,
+        });
+      }
+      continue;
+    }
+
+    const gaps = validateContract(contract, requiredFields, artifactIndex);
+
+    if (gaps.length > 0) {
+      incomplete.push({
+        ruleId: constraint.id,
+        missing: gaps,
+        severity: incompleteSeverity,
+        message: `Constraint '${constraint.id}' contract is incomplete: missing ${gaps.join(', ')}`,
+      });
+    } else {
+      complete.push({ ruleId: constraint.id, contract });
+    }
+  }
+
+  const total = registry.getAllRules().length + registry.getAllConstraints().length;
+
+  return {
+    complete,
+    incomplete,
+    missing,
+    total,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Validate a single contract for completeness.
+ *
+ * @param contract The contract to validate
+ * @param requiredFields Fields that must be present
+ * @returns Array of missing artifacts
+ */
+function validateContract(
+  contract: Contract,
+  requiredFields: Array<'behavior' | 'examples' | 'invariants'>,
+  artifactIndex?: ArtifactIndex
+): MissingArtifact[] {
+  const missing: MissingArtifact[] = [];
+
+  if (requiredFields.includes('behavior') && isFieldEmpty(contract.behavior)) {
+    missing.push('behavior');
+  }
+
+  if (requiredFields.includes('examples') && (!contract.examples || contract.examples.length === 0)) {
+    missing.push('examples');
+  }
+
+  if (requiredFields.includes('invariants') && (!contract.invariants || contract.invariants.length === 0)) {
+    missing.push('invariants');
+  }
+
+  if (artifactIndex?.tests && !artifactIndex.tests.has(contract.ruleId)) {
+    missing.push('tests');
+  }
+
+  if (artifactIndex?.spec && !artifactIndex.spec.has(contract.ruleId)) {
+    missing.push('spec');
+  }
+
+  return missing;
+}
+
+/**
+ * Check if a string field is empty or undefined.
+ */
+function isFieldEmpty(value: string | undefined): boolean {
+  return !value || value.trim() === '';
+}
+
+/**
+ * Format validation report as human-readable text.
+ *
+ * @param report The validation report
+ * @returns Formatted string
+ */
+export function formatValidationReport(report: ValidationReport): string {
+  const lines: string[] = [];
+
+  lines.push('Contract Validation Report');
+  lines.push('='.repeat(50));
+  lines.push('');
+  lines.push(`Total: ${report.total}`);
+  lines.push(`Complete: ${report.complete.length}`);
+  lines.push(`Incomplete: ${report.incomplete.length}`);
+  lines.push(`Missing: ${report.missing.length}`);
+  lines.push('');
+
+  if (report.complete.length > 0) {
+    lines.push('✓ Complete Contracts:');
+    for (const { ruleId, contract } of report.complete) {
+      lines.push(`  ✓ ${ruleId} (v${contract.version || '1.0.0'})`);
+    }
+    lines.push('');
+  }
+
+  if (report.incomplete.length > 0) {
+    lines.push('✗ Incomplete Contracts:');
+    for (const gap of report.incomplete) {
+      const icon = gap.severity === 'error' ? '✗' : gap.severity === 'warning' ? '⚠' : 'ℹ';
+      lines.push(`  ${icon} ${gap.ruleId} - Missing: ${gap.missing.join(', ')}`);
+      if (gap.message) {
+        lines.push(`     ${gap.message}`);
+      }
+    }
+    lines.push('');
+  }
+
+  if (report.missing.length > 0) {
+    lines.push('✗ No Contract:');
+    for (const ruleId of report.missing) {
+      lines.push(`  ✗ ${ruleId}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(`Validated at: ${report.timestamp}`);
+
+  return lines.join('\n');
+}
+
+/**
+ * Format validation report as JSON.
+ *
+ * @param report The validation report
+ * @returns JSON string
+ */
+export function formatValidationReportJSON(report: ValidationReport): string {
+  return JSON.stringify(report, null, 2);
+}
+
+/**
+ * Format validation report as SARIF (Static Analysis Results Interchange Format).
+ *
+ * @param report The validation report
+ * @returns SARIF JSON string
+ */
+export function formatValidationReportSARIF(report: ValidationReport): string {
+  const results = report.incomplete.map((gap) => {
+    // Use first missing item or 'contract' as fallback
+    const primaryMissing = gap.missing.length > 0 ? gap.missing[0] : 'contract';
+    
+    return {
+      ruleId: `decision-ledger/${primaryMissing}`,
+      level: gap.severity === 'error' ? 'error' : gap.severity === 'warning' ? 'warning' : 'note',
+      message: {
+        text: gap.message || `Missing: ${gap.missing.join(', ')}`,
+      },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: {
+              uri: 'registry',
+            },
+            region: {
+              startLine: 1,
+            },
+          },
+        },
+      ],
+      properties: {
+        ruleId: gap.ruleId,
+        missing: gap.missing,
+      },
+    };
+  });
+
+  const sarif = {
+    version: '2.1.0',
+    $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: 'Praxis Decision Ledger',
+            version: '1.0.0',
+            informationUri: 'https://github.com/plures/praxis',
+            rules: [
+              {
+                id: 'decision-ledger/contract',
+                shortDescription: {
+                  text: 'Rule or constraint missing contract',
+                },
+              },
+              {
+                id: 'decision-ledger/behavior',
+                shortDescription: {
+                  text: 'Contract missing behavior description',
+                },
+              },
+              {
+                id: 'decision-ledger/examples',
+                shortDescription: {
+                  text: 'Contract missing examples',
+                },
+              },
+              {
+                id: 'decision-ledger/invariants',
+                shortDescription: {
+                  text: 'Contract missing invariants',
+                },
+              },
+              {
+                id: 'decision-ledger/tests',
+                shortDescription: {
+                  text: 'Contract missing tests',
+                },
+              },
+              {
+                id: 'decision-ledger/spec',
+                shortDescription: {
+                  text: 'Contract missing spec',
+                },
+              },
+            ],
+          },
+        },
+        results,
+      },
+    ],
+  };
+
+  return JSON.stringify(sarif, null, 2);
+}

package/src/dsl/index.ts

@@ -13,6 +13,7 @@ import type {
   RuleFn,
   ConstraintFn,
 } from '../core/rules.js';
+import type { Contract } from '../decision-ledger/types.js';
 
 /**
  * Strongly typed fact definition
@@ -84,6 +85,7 @@ export interface DefineRuleOptions<TContext = unknown> {
   id: string;
   description: string;
   impl: RuleFn<TContext>;
+  contract?: Contract;
   meta?: Record<string, unknown>;
 }
 
@@ -106,11 +108,15 @@ export interface DefineRuleOptions<TContext = unknown> {
 export function defineRule<TContext = unknown>(
   options: DefineRuleOptions<TContext>
 ): RuleDescriptor<TContext> {
+  const contract = options.contract ?? (options.meta?.contract as Contract | undefined);
+  const meta = contract ? { ...(options.meta ?? {}), contract } : options.meta;
+
   return {
     id: options.id,
     description: options.description,
     impl: options.impl,
-    meta: options.meta,
+    contract,
+    meta,
   };
 }
 
@@ -121,6 +127,7 @@ export interface DefineConstraintOptions<TContext = unknown> {
   id: string;
   description: string;
   impl: ConstraintFn<TContext>;
+  contract?: Contract;
   meta?: Record<string, unknown>;
 }
 
@@ -140,11 +147,15 @@ export interface DefineConstraintOptions<TContext = unknown> {
 export function defineConstraint<TContext = unknown>(
   options: DefineConstraintOptions<TContext>
 ): ConstraintDescriptor<TContext> {
+  const contract = options.contract ?? (options.meta?.contract as Contract | undefined);
+  const meta = contract ? { ...(options.meta ?? {}), contract } : options.meta;
+
   return {
     id: options.id,
     description: options.description,
     impl: options.impl,
-    meta: options.meta,
+    contract,
+    meta,
   };
 }
 

package/src/index.browser.ts

@@ -112,6 +112,7 @@ export type {
   UnsubscribeFn,
   PluresDBInstance,
   PluresDBAdapterConfig,
+  PraxisLocalFirstOptions,
   EventStreamEntry,
   PraxisDBStoreOptions,
   StoredSchema,
@@ -125,6 +126,7 @@ export {
   createInMemoryDB,
   PluresDBPraxisAdapter,
   createPluresDB,
+  createPraxisLocalFirst,
   PraxisDBStore,
   createPraxisDBStore,
   PRAXIS_PATHS,
@@ -214,3 +216,7 @@ export {
   attachTauriToEngine,
   generateTauriConfig,
 } from './integrations/tauri.js';
+
+// Unified Integration Helpers
+export type { UnifiedAppConfig, UnifiedApp } from './integrations/unified.js';
+export { createUnifiedApp, attachAllIntegrations } from './integrations/unified.js';