@ku0/lfcc-native-ai

AI-Native operations for LFCC (Local-First Content Collaboration) native editor.

Overview

This package implements the AI Gateway and AI-Native operations per LFCC v0.9 RC and related proposals (v0.9.1, v0.9.4).

LFCC Specification Compliance

| Feature | Specification | Status | |---------|--------------|--------| | AI Gateway Envelope Validation | v0.9 RC Section 8 | Implemented | | Dry-Run Pipeline | v0.9 RC Section 8.2 | Implemented (sanitization → schema → precondition → simulation) | | Targeting Resilience Preconditions | v0.9.4 Proposal | Implemented | | Intent Tracking | v0.9.1 Proposal | Implemented |

Architecture

┌─────────────────────────────────────────┐
│ AI Request (External)                   │
└─────────────────┬───────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│ AI Envelope (Standardized Format)       │
│ - doc_frontier                          │
│ - preconditions                         │
│ - intent                                │
│ - payload                               │
└─────────────────┬───────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│ Dry-Run Pipeline                        │
│ 1. Sanitize                             │
│ 2. Schema Validate                      │
│ 3. Check Preconditions                  │
│ 4. Simulate Apply                       │
└─────────────────┬───────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│ Model Apply (If Valid)                  │
└─────────────────────────────────────────┘

Usage

import {
  AIEnvelope,
  performDryRun,
  validateAIEnvelope,
} from "@ku0/lfcc-native-ai";

const envelope: AIEnvelope = {
  version: "1.0",
  requestId: crypto.randomUUID(),
  agentId: "ai-assistant",
  docFrontier: { loro_frontier: ["peer1:5"] },
  preconditions: [{
    hard: { contextHash: "sha256:abc..." }
  }],
  intent: {
    id: "intent-123",
    category: "content_modification",
    description: "Refactor for clarity"
  },
  timestamp: new Date().toISOString(),
  payload: {
    type: "rewrite",
    target: "paragraph-456",
    content: "..."
  }
};

const result = await performDryRun(envelope);

Implementation Status

• ✅ Type definitions complete
• ✅ Dry-run pipeline with staged fail-closed validation
• ✅ Payload sanitization (script/event/url stripping)
• ✅ Preconditions and frontier deterministic validation
• ✅ Unit tests for envelope validation, sanitization, and dry-run stages
• ⏳ Advanced precondition relocation heuristics
• ⏳ Conflict resolution (planned)