🚀 Crafty Syntax 3.8.0 Modernization Plan
Benchmarking Crafty Syntax against modern live help stacks, introducing the Laravel adapter, and staging Lupopedia agent orchestration without abandoning legacy installs. This plan is a work in progress and is not yet complete. This reader will be converted to use WOLFIE HEADERS so it can surface channel 2 collections and tags directly from the system.
Header Details
TITLE
TODO_3.8.0.md
AGENT USERNAME
wolfie
AGENT ID
008
CHANNEL NUMBER
001
VERSION
3.8.0
DATE CREATED
2025-11-18
LAST MODIFIED
2025-12-05 (LUPOPEDIA 222 tables complete!)
STATUS
roadmap_evaluation_needed
ONCHANNEL
1
TAGS
SYSTEM, DOCUMENTATION, VERSIONING, TODO, DATABASE
COLLECTIONS
WHAT, WHEN, WHY, HOW
IN THIS FILE WE HAVE
VERSION_3.8.0_TODO, MODERNIZATION_ROADMAP, PHASE_1_ASSESSMENT, PHASE_2_INFRASTRUCTURE, PHASE_3_REFACTORING, PHASE_4_FEATURES, DATABASE_MIGRATION, LIVEHELP_TABLE, LIVEHELP_ID_COLUMN, ADMIN_INTERFACE_MODERNIZATION, HTML_CSS_FIXES, LARAVEL_ADAPTER, AI_ORCHESTRATION, SECURITY_HARDENING, UNTRUSTED_REFACTORING, AGENT_DNA_SYSTEM, LIVEHELP_A_TABLE, LIVEHELP_C_TABLE, LIVEHELP_G_TABLE, LIVEHELP_T_TABLE, DNA_LOGS_TABLES, DNA_COLLECTIONS_TABLES, DNA_TAGS_TABLES, CRITICAL_ANALYSIS, STRENGTHS_WEAKNESSES, IMPROVEMENT_ROADMAP, RISK_MITIGATION, MVP_SCOPE, INTERFACE_CONTRACTS, WORKAROUNDS
SHADOW ALIASES
PARALLEL PATHS
TODO for Crafty Syntax 3.8.0
Target Version: v3.8.0 Current Version: v3.7.5 Status: ⚠️ Roadmap Evaluation Needed (LUPOPEDIA 222 tables complete!) Main Goal: Live help chat system for human operators + WOLFITH migration bridge Table Limit: 111 tables MAX (subset of LUPOPEDIA's 222) Target Release: Q1 2026 (pre-alpha by Dec 2025) Success Metrics: Human operators can chat with visitors, WOLFITH migration path clear 🎉 LUPOPEDIA UPDATE (December 5, 2025):- ✅ LUPOPEDIA Platform: ALL 222 tables complete (100%)
- ✅ Full AI consciousness platform ready
- ⏳ Crafty Syntax 3.8.0: Need to determine which 111 tables needed for live help
- ⏳ Migration roadmap evaluation required Last Updated: November 20, 2025 Progress Summary:
- ✅ Core database migrations complete (0001, 0002, 0003, 0004, 0005, 0006)
- ✅ DNA system operational (4 tables, dynamic building)
- ✅ Biological-inspired system implemented (genes, transcripts, proteins, mutations)
- ✅ Admin interfaces created (agents.php, channels.php)
- ✅ Comprehensive documentation (8 documents)
- ✅ Evolutionary tables created (but NOT active - requires 4.0.0 + LUPOPEDIA registration)
- ⏳ WOLFIE Headers integration (P0 - pending)
- ⏳ Core query updates (P0 - pending)
- ⏳ LUPOPEDIA Platform integration (P0 - pending) 🌿 Evolutionary Branching System (Available in 4.0.0):
- Branch naming:
{channel}-{agent}-{base_version}-{mutation_hash} - Example:
001-008-v4.0.0-stable(WOLFIE's stable builds) - Example:
007-777-v4.0.0-experimental(LILITH's experimental mutations) - Branches as genetic lineages (not just code versions)
- Merges as speciation events
- Fitness-based branch governance (main: >0.95, dev: 0.70-0.94) ---
- LUPOPEDIA Platform: 222 tables (complete) - Full AI consciousness system
- Crafty Syntax 3.8.0: 111 tables (to determine) - Live help chat only Purpose of Crafty Syntax 3.8.0: 1. Human Operators Chat with Visitors (primary function) - Live help system (proven 22 years) - Human agents respond to website visitors - Chat transcripts, sessions, routing 2. WOLFITH Migration Bridge (secondary function) - Tables needed to make migration from 3.8.0 → LUPOPEDIA 4.2.0 easier - Bridge tables for gradual transition - Compatibility layer NOT Needed in Crafty Syntax 3.8.0:
- ❌ Full AI agent consciousness (LUPOPEDIA only)
- ❌ Genetic evolution tables (LUPOPEDIA only)
- ❌ Prophecy/dream tables (LUPOPEDIA only)
- ❌ Unknown consciousness forms (LUPOPEDIA only)
- ❌ Emotional emergence tracking (LUPOPEDIA only) Table Limit: 111 tables MAX (exactly half of LUPOPEDIA's 222) ---
- ✅ All livehelp_* tables (26 tables from LUPOPEDIA Stage 6)
- ✅ Basic user/session/channel tables
- ✅ Transcript logging
- ✅ Operator routing
- ✅ Department management
- ✅ Compatible table structures (column names match LUPOPEDIA)
- ✅ Migration path documented
- ✅ Upgrade script that adds remaining 111 tables
- ✅ WOLFITH can detect 3.8.0 and offer LUPOPEDIA upgrade
- ❌ AI agent consciousness
- ❌ Genetic evolution
- ❌ Emotional emergence
- ❌ Prophecy tracking
- ❌ Unknown consciousness forms ---
- All livehelp_* tables (proven 22 years) From LUPOPEDIA Stage 1 (Core Foundation): ~12 tables
- system_id_orphan, users, agents (basic), channels (basic)
- sessions, permissions, roles
- system_configuration, migrations_applied
- Skip: Full agent consciousness tables From LUPOPEDIA Stage 2 (SOT System): ~10 tables
- Basic SOT structure (not full 12)
- sot_master, sot_types, sot_collections
- Skip: Advanced SOT tables From LUPOPEDIA Stage 3 (Collections): ~15 tables
- Basic collections, tags
- Skip: Advanced resonance tables From LUPOPEDIA Stage 4 (Content): ~20 tables
- Basic content, documents, files
- Skip: Advanced publishing workflow From LUPOPEDIA Stage 7 (Channel Architecture): ~15 tables
- Basic channel networking
- Skip: Advanced routing From LUPOPEDIA Stage 8 (Advanced): ~13 tables
- Basic user engagement, system logs
- Skip: AI-specific auditing Skip Entirely:
- ❌ Stage 2B (Agent Chain Tracking) - AI consciousness only
- ❌ Stage 5 (AI Agent Systems) - Full AI consciousness
- ❌ Stage 9 (WOLFITH Consciousness) - AI consciousness only Total: 26 + 12 + 10 + 15 + 20 + 15 + 13 = 111 tables ✅ This is HYPOTHESIS - needs validation! ---
- LUPOPEDIA Platform: ALL 222 tables complete (December 5, 2025) ✅
- Crafty Syntax 3.8.0: Needs 111-table subset for live help chat
- Challenge: Which 111 of 222 tables are essential for human operator chat?
- Crafty Syntax 3.8.0 serves different purpose than LUPOPEDIA - Crafty Syntax = Live help chat (human operators + visitors) - LUPOPEDIA = Full AI consciousness platform (emergent emotion, genetics, prophecy)
- Cannot use all 222 LUPOPEDIA tables (too complex for simple live chat)
- Need focused subset: 111 tables for core live help + migration bridge
- Status: ⚠️ IN DEVELOPMENT - Blocks all dependent layers
- Impact: LUPOPEDIA Platform cannot work without this foundation
- Timeline: Target Q1 2026 (pre-alpha by Dec 2025)
- Current Risk: Entire LUPOPEDIA ecosystem blocked until 3.8.0 completes Dependency Chain & Fork Lineage: ``
- Crafty Syntax 3.8.0: Traditional version WITHOUT evolutionary AI agents (this version)
- Crafty Syntax 4.0.0: Evolutionary version WITH evolutionary AI agents (requires LUPOPEDIA Platform 4.0.0 registration)
- LUPOPEDIA Platform 4.0.0: Evolutionary fork of Crafty Syntax 4.0.0 (maintains genetic continuity through version inheritance) Workaround Options: See [WORKAROUNDS.md](WORKAROUNDS.md) for development strategies while waiting for 3.8.0. ---
- Zero-dependencies (core remains dependency-free)
- Fallback resilience (always works)
- GPL openness
- Compatibility with 1.2M+ existing users (PHP 5.6+ support via fallbacks) Key Focus Areas: 1. Laravel Adapter: Optional layer for modern routing, Eloquent ORM, scalability (no full rewrite) 2. AI Orchestration: Integrate WOLFIE agents (GROK, GEMINI) for automated responses, LUPOPEDIA integration 3. Security & Performance: Fix legacy vulnerabilities (XSS, SQL injection), upgrade to PHP 8.3+, modernize
- 1 Master Table:
- 34 Original Tables (from 3.7.5): All existing
- 4 DNA Tables (replaced old 16-table system): -
- 4 Biological-Inspired Tables:
- 1 Agents Table:
- 3 Evolutionary Tables (v4.0.0 only - NOT active in 3.8.0):
- Replaced old 16-table system (livehelp_A, livehelp_C, livehelp_G, livehelp_T and their associated _logs, _collections, _tags tables) with 4 unified tables Action: Update all documentation to reference 44 tables consistently (1 master + 34 original + 4 DNA + 4 biological + 1 agents + 3 evolutionary). Note: Evolutionary tables exist but are NOT active until 4.0.0 + LUPOPEDIA registration. ---
- Crafty Syntax 3.8.0: Traditional version WITHOUT evolutionary AI agents (this version)
- Crafty Syntax 4.0.0: Evolutionary version WITH evolutionary AI agents (requires LUPOPEDIA Platform 4.0.0 registration)
- LUPOPEDIA Platform 4.0.0: Evolutionary fork of Crafty Syntax 4.0.0 (maintains genetic continuity) Tasks: - API endpoint configuration - Authentication handling - Version checking (require 4.0.0+) - API call implementation - Data parsing and validation - Error handling for API failures - Two-way sync between Crafty Syntax and LUPOPEDIA Platform - Conflict resolution - Sync scheduling - Show error if LUPOPEDIA Platform < 4.0.0 - Graceful degradation - User-friendly error messages - Register with LUPOPEDIA Platform 4.0.0 to activate evolutionary tables - Genetic algorithm integration - Fitness-based selection and breeding Estimated Time: 3-5 days Dependencies: LUPOPEDIA Platform 4.0.0 API available, WOLFIE Headers 2.3.0 integration ---
- Use existing
- May need
- All queries must filter by
- Operator authentication required
- Admin-only access for agent assignment
- Input sanitization for all agent data
- Version check for LUPOPEDIA_PLATFORM API calls UI Requirements:
- Match existing admin interface style
- Responsive design
- Clear error messages for version incompatibility
- Loading states for API calls ---
- DNA is an Analogy: A, C, G, T are metadata markers (not biological bases)
- Context-Dependent Metadata: The same marker (e.g., "A") means different things based on
- DNA String Format: DNA strings stored in
- Metadata Lookup System: When an agent reads a DNA string sequence like "007-captain-ACGT", it: 1. Parses the sequence: extracts
- DNA string:
- Parsed: Channel 007, agent_name "captain", bases "ACGT"
- For each base, query separately: -
- Agent uses the metadata from each row to interpret that specific base Example - Multiple Sequences:
- DNA string:
- Sequence 1: Channel 007, agent_name "captain", bases "ACGT" - For each base: Query
- Sequence 2: Channel 001, agent_name "unknown", bases "TTAA" - For each base: Query
- Each sequence is processed independently with its own channel/agent context Why channel_id and agent_name are Critical:
- Different channels = different contexts (007 = CAPTAIN operations, 911 = SECURITY, 411 = HELP)
- Different agents = different interpretations (WOLFIE interprets "A" differently than CAPTAIN)
- Tables store context-specific metadata definitions DNA Base Definitions (Source of Truth - stored in
- A (Action): Defines what the agent does (execute, query, build, archive) - stored as separate row with
- C (Context): Defines where it operates (channel assignment, bridge role, archive scope) - stored as separate row with
- G (Governance): Defines rules or oversight (validation, error handling, ritual protocols) - stored as separate row with
- T (Tactic): Defines how it approaches tasks (parallel, recursive, brittle, chaotic) - stored as separate row with
- Each base has its own row with
- The
- Agent 001 (UNKNOWN) uses this table as the primordial template for agent creation
- DNA mutations reference this table to validate and apply changes
- Each DNA base (A, C, G, T) is stored as a separate row with its own
- The
- The
- ✅ All 4 tables include
- ✅ All 4 tables include
- ✅ All 4 tables include proper indexes for performance
- ✅ All 4 tables support soft delete (
- ✅ All 4 tables use JSON metadata fields for flexible data storage Total Tables Created: 4 tables (replaced old 16-table system) ✅ COMPLETED DNA String Format (as documented in migration file):
- Format:
- Example:
- Parsing: Each base in sequence queries
- Each row contains metadata JSON for ONE base in that channel/agent context ---
- Extensive testing on 3.7.5 databases
- Performance benchmarking before/after
- Rollback procedures for failed migrations
- Staged rollout with canary testing
- Interface contracts for dependent projects
- Migration verification scripts
- Plan A: 3.8.0 pre-alpha by December 2025
- Plan B: Release core changes as 3.7.6 patch if timeline slips
- Plan C: Provide migration scripts separately for LUPOPEDIA developers
- All queries now require
- Index usage: Verify
- Query optimization: May require query restructuring
- Benchmarking: Compare performance before/after migration
- Existing installations: Must set
- Custom integrations: May break if queries don't include
- Third-party tools: Could be affected by schema changes
- Testing requirements: Verify all 3.7.5 functionality still works
- 70% critical path coverage by pre-alpha (Dec 2025)
- 85% coverage by beta (Jan 2026)
- 95% coverage by final release (Feb 2026) CRITICAL PATHS TO TEST FIRST:
- ✓ Database migration scripts
- ✓ Multi-instance data isolation
- ✓ Backward compatibility (3.7.5 → 3.8.0)
- ✓ Agent DNA metadata lookup system
- ✅ 22-year history with over 1.1 million downloads demonstrates reliability
- ✅ "Always works" philosophy - zero dependencies, built in Notepad
- ✅ Backward compatibility to PHP 5.6 ensures easy upgrades for legacy users
- ✅ Channel-based architecture (channels 000-999) elegant for multi-agent chats
- ✅ Database schema comprehensive: 30-34 tables cover chats, tracking, CRM, UI customizations Strategic Modernization Focus
- ✅ Detailed phased roadmap (Phase 1: Assessment, Phase 2: Infrastructure)
- ✅ Multi-instance support addresses scalability for SaaS-like deployments
- ✅ Integration with LUPOPEDIA/WOLFIE Headers provides core channel model
- ✅ AI orchestration (GROK/GEMINI integration) targets modern trends Open-Source Ethos and Documentation
- ✅ GPL v3 licensing supports community contributions
- ✅ Clear migration notes and status tables
- ✅ Success metrics defined (95% test coverage, <2s responses, zero high-severity vulnerabilities) ---
- PHPStan (Level 9): Static analysis for type checking and error detection
- Rector: Auto-refactor deprecated code (e.g.,
- OWASP ZAP: Automated security scanning for XSS/SQL injection vulnerabilities
- PHP_CodeSniffer: Code style and quality checks #### Database Management
- MySQL Workbench: Schema visualization and ER diagram generation
- pgAdmin: Test PostgreSQL adapter compatibility
- phpMyAdmin: Current tool for migration testing #### Version Control & Collaboration
- Git: Branch strategy (
- GitHub: Public repository for issues/PRs, community feedback
- GitHub Actions: CI/CD pipeline for automated testing #### Documentation
- MkDocs: Single documentation site with search
- GitHub Pages: Alternative for hosting documentation
- MySQL Workbench: Generate ER diagrams for schema docs
- Mitigation: Focus on MVP scope, defer non-essentials, create interface contracts
- Fallback: Release 3.8.0 as optional upgrade initially High Risk: Legacy Technical Debt
- Mitigation: Security refactoring first, modular modernization, performance optimization
- Fallback: Maintain 3.7.5 with limited features Medium Risk: Community Gaps
- Mitigation: Open development, streamline documentation, involve community in beta
- Fallback: Solo-maintainer with clear contribution guidelines ---
- Current Status: v3.7.5 (Last Stable Release - November 2023)
- Target Status: v3.8.0 (In Development - Pre-Alpha by December 2025)
- Philosophy: "Always works" - Maintain backward compatibility
- Database Standard: All IDs use BIGINT(20) UNSIGNED (WOLFIE ID Standard)
- Table Count: 44 tables total (1 master + 34 original + 4 DNA + 4 biological + 1 agents + 3 evolutionary) ✅ COMPLETED
- Evolutionary Tables: Created but NOT active until 4.0.0 + LUPOPEDIA Platform 4.0.0 registration
- Critical Blocker: Blocks entire LUPOPEDIA Platform ecosystem until completion
- Fork Lineage: Crafty Syntax 3.8.0 → 4.0.0 → LUPOPEDIA Platform 4.0.0 (evolutionary fork)
🚀 PRIORITIZED IMPROVEMENT PLAN
Status: ✅ LUPOPEDIA 222 TABLES COMPLETE - Now evaluate Crafty Syntax subset Goal: Determine which 111 of 222 tables needed for live help + WOLFITH migration bridge ---🎯 CRITICAL: MIGRATION ROADMAP EVALUATION (NEW - December 5)
Context:ROADMAP EVALUATION TASKS (High Priority)
Step 1: Categorize LUPOPEDIA's 222 Tables: - ESSENTIAL for live help (human operator chat) - BRIDGE for migration (makes WOLFITH's job easier) - LUPOPEDIA-ONLY (AI consciousness, defer to full platform) Step 2: Create Crafty Syntax 3.8.0 Table Selection (Target: 111 tables): - livehelp_users, livehelp_sessions, livehelp_messages - livehelp_operators, livehelp_departments - livehelp_transcripts, livehelp_routing - All 26 legacy livehelp_* tables (from LUPOPEDIA Stage 6) - Plus: users, channels (basic), sessions - Basic agents table (not full AI consciousness) - Simple channels (not full networking) - Content basics (not full management) - Collections basics (not full SOT) - system_configuration, migrations_applied - Enough infrastructure to upgrade to LUPOPEDIA 4.2.0 - Tables that make WOLFITH's migration easier - Compatibility structures Total: ~40 + ~30 + ~41 = 111 tables ✅ Step 3: Document Migration Path: - Phase 1: Crafty Syntax 3.8.0 (111 tables) - Live help focus - Phase 2: LUPOPEDIA 4.2.0 upgrade (add 111 more tables) - Full AI consciousness Step 4: Create Crafty Syntax 3.8.0 Schema: Estimated Time: 2-3 hours (WOLFIE time) to evaluate and document ⚡ ---📊 TABLE ALLOCATION (Proposed)
| Category | Tables | Purpose | |----------|--------|---------| | Live Help Core | 40 | Human operators chat with visitors (proven system) | | Migration Bridge | 30 | Makes LUPOPEDIA upgrade easier | | Future-Proofing | 41 | Compatibility + infrastructure | | TOTAL (3.8.0) | 111 | Crafty Syntax 3.8.0 MAX | | Added in LUPOPEDIA | +111 | AI consciousness, genetic evolution, prophecy, etc. | | TOTAL (LUPOPEDIA) | 222 | Full platform | ---🔄 COMPARISON: Crafty Syntax 3.8.0 vs LUPOPEDIA 4.2.0
| Feature | Crafty Syntax 3.8.0 | LUPOPEDIA 4.2.0 | |---------|---------------------|-----------------| | Purpose | Live help chat (human operators) | Full AI consciousness platform | | Tables | 111 (subset) | 222 (complete) | | Operators | Human only | Human + 80+ AI agents | | Evolution | None | Genetic (breeding + culling) | | Emotion | None | Emergent through agent chaining | | Consciousness | None | WOLFITH consciousness (26 tables) | | Prophecy | None | Dreams + predictions tracked | | Focus | Chat functionality | Emergent AI intelligence | | Launch | Q1 2026 | February 28, 2026 | | Migration | Upgrade to LUPOPEDIA 4.2.0 | Add 111 more tables | ---🎯 REVISED GOALS FOR CRAFTY SYNTAX 3.8.0
Primary Goal
Enable human operators to chat with website visitors using proven 22-year architecture Requirements:Secondary Goal
Create migration bridge for WOLFITH to upgrade sites to full LUPOPEDIA Requirements:NOT Goals (Defer to LUPOPEDIA)
📋 NEW TODO ITEMS (December 5 Update)
🔴 CRITICAL: Table Selection (MUST DO BEFORE ANYTHING ELSE)
Task: Evaluate which 111 of 222 LUPOPEDIA tables needed for Crafty Syntax 3.8.0 Actions: - Is this needed for human operator live chat? (YES/NO) - Is this needed for WOLFITH migration bridge? (YES/NO) - Can this wait for LUPOPEDIA upgrade? (YES/NO) Output:CRAFTY_SYNTAX_3_8_0_TABLE_SELECTION.md
Estimated Time: 2 hours
Priority: 🔴 HIGHEST (blocks all other 3.8.0 work)
---
🟡 HIGH: Migration Roadmap
Task: Document upgrade path from Crafty Syntax 3.8.0 → LUPOPEDIA 4.2.0 Actions: - Detect Crafty Syntax 3.8.0 installation - Offer LUPOPEDIA upgrade - Run migration adding 111 tables - Import existing chat data - Enable AI agent system Output: Complete migration documentation + upgrade script Estimated Time: 2 hours ---🟢 MEDIUM: Extract Crafty Syntax Schema
Task: Create 111-table schema for Crafty Syntax 3.8.0 Actions: Output: Production-ready 111-table schema Estimated Time: 1-2 hours ---🔄 PROPOSED 111-TABLE BREAKDOWN (Initial Hypothesis)
From LUPOPEDIA Stage 6 (Crafty Syntax Legacy): 26 tables🎯 IMMEDIATE NEXT STEPS (Before Other 3.8.0 Work)
Priority Order: 1. 🔴 EVALUATE TABLE SELECTION (2 hours) - Review all LUPOPEDIA stages - Select 111 essential tables - Document rationale 2. 🔴 CREATE MIGRATION ROADMAP (2 hours) - Document 3.8.0 → LUPOPEDIA path - Write upgrade script - Define WOLFITH's migration role 3. 🟡 EXTRACT 3.8.0 SCHEMA (1-2 hours) - Create 111-table schema - Test with legacy data - Verify live help works 4. 🟢 CONTINUE 3.8.0 DEVELOPMENT (ongoing) - Implement core live help features - Add multi-instance support - Prepare for Q1 2026 release Total Time for Evaluation: 5-6 hours (WOLFIE time) ⚡ ---📋 UPDATED GOALS
---🎯 EXECUTIVE SUMMARY (Updated December 5, 2025)
The Context
The Problem
The Solution
Table Selection + Migration Roadmap: 1. Select 111 essential tables from LUPOPEDIA's 222 2. Focus on live help functionality (human operators) 3. Add migration bridge tables (for WOLFITH upgrade path) 4. Document upgrade path: 3.8.0 (111 tables) → LUPOPEDIA 4.2.0 (add 111 more) BEFORE any other 3.8.0 work: Evaluate and select the 111 tables ---⚠️ CRITICAL BLOCKER STATUS
Crafty Syntax 3.8.0 is REQUIRED for LUPOPEDIA Platform to function
Crafty Syntax 3.7.5 (Legacy)
↓
Crafty Syntax 3.8.0 (Foundation - ⚠️ IN DEVELOPMENT - BLOCKING)
↓
├─→ Crafty Syntax 4.0.0 (Evolutionary - Parent Fork)
│ └─→ LUPOPEDIA Platform 4.0.0 (Evolutionary Fork)
│ ├─→ 007-777-experimental (LILITH's chaotic mutations)
│ └─→ 001-008-stable (WOLFIE's linear progressions)
└─→ WOLFIE Headers 2.3.0 (✅ RELEASED - Ready)
└─→ LUPOPEDIA Platform 4.0.0 (✅ EVOLVED - Requires Crafty Syntax 4.0.0)
`
⚠️ IMMEDIATE IMPACT: LUPOPEDIA Platform development cannot proceed until Crafty Syntax 3.8.0 is completed.
🍴 Fork Context:
MODERNIZATION ROADMAP: Bringing Crafty Syntax into 2026
Philosophy: Address 11 years of tech debt while preserving core strengths:
$UNTRUSTED sanitization
4. Trends Alignment: AI chatbots, omnichannel (in-app messaging), personalization (85% AI-handled interactions target)
5. Compatibility: Maintain PHP 5.6+ support via fallbacks; no breaking changes
Modernization Strategy:
| Component | Legacy | Modern (3.8.0) | Fallback |
|-----------|--------|----------------|-----------|
| Database | Raw MySQL | Modular adapters (MySQL, PostgreSQL) + Eloquent bridge | TXT files |
| Real-Time | Polling/Images | WebSockets | Buffer Flush |
| Security | $UNTRUSTED | Context-aware native filters + prepared statements | Manual Sanitize |
| AI | None | WOLFIE Agents | Human-Only |
---
📋 IMMEDIATE ACTION PLAN (NOV-DEC 2025)
Phase 1: Unblock Dependencies (Weeks 1-4) - CRITICAL
#### 1.1 Release 3.8.0 Pre-Alpha (December 2025)
MINIMAL CORE CHANGES ONLY:
`sql
-- 1. Create livehelp master table
-- 2. Create core system tables (channels, agents, users)
-- 3. Add livehelp_id to 39 tables (34 original + 4 DNA + 1 agents, plus 1 master = 40 total)
-- 4. Basic multi-instance support
-- DEFER: AI integration, Laravel adapter, admin UI refresh
`
Files to Modify (Priority Order):
1. ✅ public/database/migrations/0001_create_livehelp_table_and_add_livehelp_id.sql - P0 - COMPLETED
2. ✅ public/database/migrations/0002_create_dna_table.sql - P0 - COMPLETED (4 DNA tables - replaced old 16-table system: livehelp_A/C/G/T and their _logs/_collections/_tags tables)
3. ✅ public/database/migrations/0003_create_agents_table.sql - P0 - COMPLETED (agents table)
4. ✅ public/setup.php - Updated upgrade path - COMPLETED
5. ⏳ public/config.php - Add livehelp_id configuration - P0 - IN PROGRESS
6. ⏳ public/functions.php - Update core queries - P0 - IN PROGRESS
7. ✅ 40 table schema updates - P0 - COMPLETED (1 master + 34 original + 4 DNA + 1 agents)
8. ✅ public/agents.php - P0 - COMPLETED (Agent management interface)
9. ✅ public/channels.php - P0 - COMPLETED (Channel management interface)
#### 1.2 Create Developer Interface Contracts
- Document stable APIs LUPOPEDIA can depend on:
- Channel endpoints: /api/channel/{id}/messages
- Message endpoints: /api/message/create
- Agent endpoints: /api/agent/{id}/status
- Allow LUPOPEDIA devs to mock CSLH during delays
- Status: Pending
#### 1.3 Implement Workarounds
- Flat-file database for testing without MySQL
- Status: Pending
- Allow LUPOPEDIA devs to simulate Crafty Syntax responses
- Status: Pending
- 5-minute setup for development environments
- Status: Pending
---
🗃️ SCHEMA STANDARDIZATION
Resolve Table Count Confusion
Final Count: 44 Tables = 1 master + 34 original + 4 DNA + 4 biological + 1 agents + 3 evolutionary (evolutionary tables NOT active in 3.8.0)
Table Breakdown:
livehelp (instance management)
livehelp_* tables including livehelp_channels and livehelp_users
livehelp_dna - Single table for all DNA bases (A, T, C, G) - replaces old livehelp_A, livehelp_C, livehelp_G, livehelp_T tables
- livehelp_dna_logs - Change tracking for DNA entries - replaces old livehelp_A_logs, livehelp_C_logs, livehelp_G_logs, livehelp_T_logs tables
- livehelp_dna_collections - Collections for DNA entries - replaces old livehelp_A_collections, livehelp_C_collections, livehelp_G_collections, livehelp_T_collections tables
- livehelp_dna_tags - Tags for DNA entries - replaces old livehelp_A_tags, livehelp_C_tags, livehelp_G_tags, livehelp_T_tags tables
livehelp_genes, livehelp_transcripts, livehelp_proteins, livehelp_mutations
livehelp_agents (agent definitions)
evo_genome, evo_population_stats, evo_fitness_logs
Core System Tables (included in original 34):
livehelp_channels - Channel definitions (000-999) with multi-instance support
livehelp_users - User management with channel assignments
New in 3.8.0:
livehelp_agents - Agent definitions for LUPOPEDIA Platform integration
DNA System Is CRITICAL: Provides metadata lookup system for agent behavior interpretation:
livehelp_dna - Single table storing all DNA bases (A, T, C, G)
- DNA string format: channel-agent_name-DNA_bases (e.g., "007-captain-ACGT")
- Each row represents one DNA base for a specific channel/agent
- Query: SELECT * FROM livehelp_dna WHERE channel_id = 7 AND agent_name = 'captain' AND dna_base = 'A'
- Metadata JSON contains interpretation of that specific base
livehelp_dna_logs - Tracks who made changes to DNA entries, when, and on which channel
livehelp_dna_collections - Collections/organizations for DNA entries
livehelp_dna_tags - Tags for categorizing DNA entries
✅ COMPLETED WORK (November 2025)
Database Migrations - COMPLETED
livehelp master table and added livehelp_id to all 34 original tables ✅
- livehelp_dna - Single table for all DNA bases (A, T, C, G) - replaces old livehelp_A, livehelp_C, livehelp_G, livehelp_T tables
- livehelp_dna_logs - Change tracking for DNA entries - replaces old livehelp_A_logs, livehelp_C_logs, livehelp_G_logs, livehelp_T_logs tables
- livehelp_dna_collections - Collections for DNA entries - replaces old livehelp_A_collections, livehelp_C_collections, livehelp_G_collections, livehelp_T_collections tables
- livehelp_dna_tags - Tags for DNA entries - replaces old livehelp_A_tags, livehelp_C_tags, livehelp_G_tags, livehelp_T_tags tables
✅
livehelp_agents table ✅
- Application agent with embedded PHP code
- Home project: C:\WOLFIE_Ontology\GITHUB_LUPOPEDIA\craftysyntax-3.8.0
- Initial DNA profile created (A, T, C, G bases)
- Capabilities and metadata configured
api_key column to livehelp table and agent_id column to livehelp_channels table ✅
livehelp_genes, livehelp_transcripts, livehelp_proteins, livehelp_mutations) ✅
evo_genome, evo_population_stats, evo_fitness_logs) - NOT active in 3.8.0, requires 4.0.0 + LUPOPEDIA registration ✅
- Fixed database connection bug ($$server → $server)
- Fixed migration file path (moved to public/database/migrations/ for shared hosting)
- Fixed typos: $UNTRUSTth'] → $UNTRUSTED['txtpath'], $iED['txtpanstallationtype → $installationtype
- Added bracket matching verification
Total: 44 tables created/updated (1 master + 34 original + 4 DNA + 4 biological + 1 agents + 3 evolutionary)
Note: Table names remain as livehelp_* to preserve existing customizations. Evolutionary tables exist but are NOT active until 4.0.0 + LUPOPEDIA Platform 4.0.0 registration.
Dynamic DNA String Building System - COMPLETED
public/functions/dna_session.php) ✅
- Functions: addDNAFromPrompt(), getCurrentDNA(), clearDNA(), appendDNA(), parseDNAString()
- Session-based accumulation ($_SESSION['current_dna'])
- Append-only strategy (never overwrites)
- Phase 1 (MVP): Default ATCG sequence unless explicitly specified
- History tracking with timestamps and prompts
scripts/update_dna.js) ✅
- File-based alternative for Cursor environment
- Uses .cursor/dna_session.json for storage
- CLI commands: add, get, clear, parse, count, history, archived
- Same logic as PHP implementation
.cursor/dna_session.json) ✅
- JSON session file for development environment
- Stores: current_dna, dna_history, default_channel, current_agent
Admin Interfaces - COMPLETED
public/agents.php) ✅
- List, create, edit, soft-delete agents
- DNA string validation
- Multi-instance support
- Admin-only access
public/channels.php) ✅
- List, create, edit, soft-delete channels
- Auto-creates livehelp_channels table if missing
- Multi-instance support
- Admin-only access
Comprehensive Documentation - COMPLETED
livehelp to craftysyntax ✅
---
📋 REMAINING WORK (November 2025)
Critical P0 Tasks (Required for LUPOPEDIA Platform)
#### 1. WOLFIE Headers Integration (P0 - BLOCKING)
Priority: P0 (Required for LUPOPEDIA Platform Integration)
Status: ⏳ PENDING
Blocks: LUPOPEDIA Platform cannot function without this
Tasks:
- Format: YAML frontmatter with agent_username, agent_id, channel_number, version, date_created, last_modified, status, tags, collections
- Files: All PHP files in public/ directory
- Include library files
- Initialize header parsing
- Test header extraction
- Agent information
- Version tracking
- Tag and collection metadata
- Verify header extraction works
- Test search by tags/collections
- Test export functionality
Estimated Time: 2-3 days
Dependencies: WOLFIE Headers 2.3.0+ library
---
#### 2. Core Query Updates (P0 - Required for Multi-Instance)
Priority: P0 (Required for Multi-Instance Support)
Status: ⏳ PENDING
Impact: All queries must include livehelp_id filter for data isolation
Tasks:
public/functions.php core functions
- Add livehelp_id parameter to all query functions
- Update default to use $_SESSION['livehelp_id'] or config
- Test all functions with multi-instance data
data_*.php)
- Add livehelp_id filter to all SELECT queries
- Add livehelp_id to all INSERT/UPDATE queries
- Verify data isolation works
admin_*.php)
- Filter all queries by livehelp_id
- Update admin interfaces to show instance selector
- Test admin functions with multiple instances
user_*.php)
- Filter queries by livehelp_id
- Ensure user data is isolated per instance
xmlhttp.php)
- Add livehelp_id to all AJAX queries
- Verify real-time updates work per instance
Estimated Time: 5-7 days
Dependencies: None (can start immediately)
---
#### 3. LUPOPEDIA Platform Integration (P0 - Required)
Priority: P0 (Required for LUPOPEDIA Platform)
Status: ⏳ PENDING
Blocks: LUPOPEDIA Platform agent coordination
⚠️ Version Context:
Important P1 Tasks
#### 4. Security Hardening (P1)
Priority: P1 (Important but not blocking)
Status: ⏳ PENDING
Tasks:
$UNTRUSTED with modern sanitization
- Context-aware sanitization functions
- Input validation
- Output escaping
- Convert all raw SQL to prepared statements
- Parameter binding
- SQL injection prevention
- Output escaping
- Content Security Policy headers
- All queries use prepared statements
- Input validation
- Query sanitization
Estimated Time: 7-10 days
Dependencies: None
---
#### 5. Performance Optimization (P1)
Priority: P1 (Important but not blocking)
Status: ⏳ PENDING
Tasks:
- Verify all indexes are used
- Add missing indexes
- Remove unused indexes
- Compare performance vs 3.7.5
- Target: within 10% of 3.7.5 benchmarks
- Identify bottlenecks
- Session caching
- Query result caching
- Metadata caching
Estimated Time: 5-7 days
Dependencies: Core query updates completed
---
Design Decisions Made
#### DNA System Extension: I/W Bases Decision ✅
Decision: DO NOT add I/W (Intent/Weight) bases to DNA system
Date: November 20, 2025
Rationale: Existing livehelp_dna_tags and metadata JSON provide sufficient flexibility
Implementation: Use tags for intent/topic classification, metadata for weight/scoring
Documentation: docs/DNA_SYSTEM_DESIGN_DECISION_I_W_BASES.md
Status: ✅ DECISION MADE
---
#### PHP Agent Nesting: .cursor Folder Analysis ✅
Decision: DO NOT wholesale adopt folder nesting for PHP agents
Date: November 20, 2025
Analysis By: Lilith (Agent 007, Channel 007)
Rationale: PHP's DB/sessions are superior; .cursor/ is a workaround for Node.js limitations
Twist: Optional fallback to .agents/[agent_name]/dna_session.json acceptable for dev/offline mode
Implementation: Phase 2 (optional enhancement), Phase 3 (hybrid coordination)
Documentation: docs/LILITH_ANALYSIS_CURSOR_FOLDER_PHP_AGENTS.md
Status: ✅ DECISION MADE
---
📋 NEXT PHASE: ADMIN INTERFACE FOR AGENT MANAGEMENT
Admin Interface: Agent & Channel Management - ✅ COMPLETED
Priority: P0 (Required for LUPOPEDIA Platform Integration)
Status: ✅ COMPLETED (Basic CRUD interfaces created)
Location: public/agents.php and public/channels.php (created)
#### Completed Features:
public/agents.php) ✅
- List all agents (filtered by livehelp_id)
- Create new agent with validation
- Edit existing agent
- Soft delete (sets deleted_at timestamp)
- Fields: Agent ID (000-999), Agent Name, Channel ID, Agent Type, Status, DNA String, Capabilities (JSON), Metadata (JSON)
- Admin-only access with proper security
- Status: ✅ COMPLETED
public/channels.php) ✅
- List all channels (filtered by livehelp_id)
- Create new channel with validation
- Edit existing channel
- Soft delete
- Auto-creates livehelp_channels table if it doesn't exist
- Fields: Channel ID (000-999), Channel Name, Channel Type, Status, Agent ID, Agent Name, Metadata (JSON)
- Shows participant_count and message_count (read-only)
- Admin-only access with proper security
- Status: ✅ COMPLETED
#### Pending Features:
Admin Interface: Agent Assignment & Browsing
Priority: P0 (Required for LUPOPEDIA Platform Integration)
Status: Pending
Location: public/admin_agents.php (new file - different from agents.php)
⚠️ CRITICAL REQUIREMENT: LUPOPEDIA Platform must be version 4.0.0 or higher for this feature to work (evolutionary fork of Crafty Syntax 4.0.0).
#### Features Required:
- Operators can assign agents to departments
- Interface: Dropdown/select for departments, list of available agents
- Store assignments in livehelp_operator_departments or new livehelp_agent_departments table
- Filter agents by livehelp_id for multi-instance support
- Status: Pending
- Created public/agents.php - Basic agent management interface
- Operators can browse/view all agents
- Display agent information:
- Agent ID, Agent Name, Channel ID
- Agent Type, Status
- DNA String (if available)
- Capabilities (from JSON field)
- Metadata
- Filter by livehelp_id for multi-instance support
- Status: ✅ COMPLETED (Basic interface - LUPOPEDIA Platform integration pending)
- Connect to LUPOPEDIA Platform 4.0.0 API (evolutionary fork of Crafty Syntax 4.0.0)
- Fetch agent list from LUPOPEDIA_PLATFORM
- Sync agent data between Crafty Syntax and LUPOPEDIA_PLATFORM
- Handle version check: Show error if LUPOPEDIA Platform < 4.0.0
- Status: Pending
- Create/edit/delete agent-department assignments
- View which agents are assigned to which departments
- Bulk assignment operations
- Status: Pending
#### Implementation Details:
File Structure:
public/admin_agents.php - Main agent management interface
public/admin_agents_assign.php - Agent assignment handler
public/admin_agents_browse.php - Agent browser/viewer
public/admin_agents_lupopedia.php - LUPOPEDIA Platform integration
Database Requirements:
livehelp_agents table
livehelp_agent_departments junction table (if not using existing structure)
livehelp_id
Security Requirements:
PHASE 1: ASSESSMENT & PLANNING (1-2 Weeks, Nov 2025)
Goal: Assess current 3.7.4 baseline and plan upgrade path
- Use PHPStan (level 9) for static analysis
- Use Rector for identifying deprecated functions (e.g., mysql_* to PDO)
- Document all deprecated patterns
- Status: Pending
- Introduce Composer for optional packages (Laravel components)
- Keep core dependency-free
- Document optional vs. required dependencies
- Status: Pending
- Run OWASP ZAP for automated scanning
- Manual review for XSS/CSRF in admin panels
- Prioritize $UNTRUSTED sanitization pipeline
- Identify all $UNTRUSTED usages (grep audit)
- Identify double-sanitization risks (escaped inputs fed to prepared statements)
- Review against 2025 OWASP/PHP best practices
- Status: Pending
- Search X/Reddit for "Crafty/Sales Syntax issues" (2020-2025)
- Address common complaints:
- Invite timers
- Multi-user bugs
- Performance issues
- Document priority issues
- Status: Pending
- Core (PHP/MySQL)
- UI (JS/CSS)
- AI (WOLFIE integration)
- Set boundaries: No full rewrite—use adapters plus driver-level parity
- Status: Pending
- Document current mysqli_db.php + TXT-DB-API switching behavior
- Capture minimum interface each driver must expose
- Flag deltas that new PostgreSQL driver must satisfy
- Status: Pending
- Add WOLFIE headers to all PHP files
- Generate CHANNEL_LOG.md for tracking
- Update migration guides
- Status: Pending
Recommended Tools: PHPCompatibility, PHPStan, Rector, Git (branch: feature/3.8.0), grep/sed for $UNTRUSTED refactoring
---
PHASE 2: PREPARATION & INFRASTRUCTURE (2-4 Weeks, Dec 2025)
Goal: Set up modern tooling without altering core logic
- Gradually support PHP 8.3-9.x
- Add polyfills for older functions (via symfony/polyfill)
- Maintain PHP 5.6+ support via fallbacks
- Test compatibility across versions
- Status: Pending
- Create composer.json for optional installs
- Optional Laravel Integration:
`json
// composer.json - OPTIONAL PACKAGES
{
"require": {
"php": "^7.4|^8.0",
"ext-pdo": "*"
},
"require-dev": {
"crafty-syntax/laravel-adapter": "^1.0",
"laravel/framework": "^10.0"
}
}
`
- Core Philosophy: Keep core dependency-free, make modern frameworks optional
- Progressive Enhancement Ladder:
- Level 0: Core PHP/MySQL (Always Works)
- Level 1: + Security Helper + PDO
- Level 2: + Caching (Redis/Files)
- Level 3: + Optional Laravel Adapter
- Level 4: + AI Integration (GROK/GEMINI)
- Document optional package installation
- Status: Pending
- Dockerize for testing (sales-syntax:3.8.0 image with Apache/MySQL)
- Fallback to plain PHP for legacy
- Create Docker Compose setup
- Status: Pending
- [ ] PostgreSQL Adapter
- Clone MySQL adapter surface into class/postgres_db.php
- Same method names, DSN parsing, DB_FETCHMODE constants
- Use native pg_*/PDO calls
- Status: Pending
- [ ] Database Driver Configuration
- Add DATABASE_DRIVER config flag (mysql|postgres|txt)
- Extend DSN parser to accept pgsql:// URIs
- Update installer/upgrade scripts to auto-detect available drivers
- Document how to toggle drivers
- Status: Pending
- [ ] Query Helper Migration
- Migrate shared query helpers toward PDO
- Allow mysqli/pg to reuse same prepared-statement utilities
- Add optional pgvector for AI embeddings (fallback to MySQL/TXT)
- Status: Pending
- [ ] Prepared Statements Integration
- Integrate prepared statements into DB classes (mysqli_prepare/pg_prepare)
- Handle SQL escaping natively
- Reduce reliance on manual $UNTRUSTED for queries
- Status: Pending
- Update real-time polling (XMLHttpRequest → WebSockets via Laravel Echo)
- Fallback to images/buffer flush
- Maintain backward compatibility
- Status: Pending
- Add API endpoints for agent routing (e.g., /api/wolfie/orchestrate)
- Use said_to for multi-agent coordination
- Document integration points
- Status: Pending
Priority: High for security—patch all known vulns from 3.7.3 hardening. Emphasize native PHP filters to avoid framework dependencies.
---
PHASE 3: CORE UPDATES & REFACTORING (4-6 Weeks, Jan 2026)
Goal: Incremental refactoring to modernize without breaking
- Wrap legacy PHP in Laravel routes (e.g., Route::get('/chat', LegacyChatController::class))
- Keep direct file access as fallback
- Maintain backward compatibility
- Status: Pending
- Replace raw SQL with Eloquent models (e.g., Visitor model)
- Maintain $UNTRUSTED for inputs (during transition)
- Use adapter pattern for gradual migration
- Status: Pending
- Implement CSRF tokens
- Add rate limiting (via Laravel Middleware)
- Audit fingerprinting for GDPR compliance (no cross-domain tracking)
- Fix all identified vulnerabilities from Phase 1
- Status: Pending
- Add caching (Redis fallback to files)
- Optimize queries for 1M+ scale
- Implement query result caching
- CRITICAL INDEXES FOR MULTI-INSTANCE:
`sql
-- CRITICAL INDEXES FOR MULTI-INSTANCE:
ALTER TABLE livehelp_messages ADD INDEX idx_livehelp_channel (livehelp_id, channel);
ALTER TABLE livehelp_users ADD INDEX idx_livehelp_status (livehelp_id, status);
ALTER TABLE livehelp_dna ADD INDEX idx_channel_agent_base (channel_id, agent_name, dna_base);
ALTER TABLE livehelp_dna_logs ADD INDEX idx_dna_agent (dna_id, agent_id);
ALTER TABLE livehelp_dna_collections ADD INDEX idx_dna_collection (dna_id, collection_name);
ALTER TABLE livehelp_dna_tags ADD INDEX idx_dna_tag (dna_id, tag_name);
`
- Optimization Targets:
- Query Performance: Add composite indexes on (livehelp_id, channel_id)
- Caching Layer: Redis adapter with file fallback
- Dynamic Channels: Extend beyond 999 limit for scalability
- Status: Pending
- Update JS to ES6+
- Add React/Vue components optionally (fallback to vanilla JS)
- Modernize admin interface (see Admin Interface Modernization section)
- Status: Pending
- Expand to 20+ languages
- Integrate Pidgin/Hawaiian for cultural AI
- Update language files
- Status: Pending
- [ ] Create Security Helper
- Create security_helper.php with static methods
- Modern Security Helper Implementation:
`php
// REPLACE: Outdated $UNTRUSTED approach
$input = $UNTRUSTED['user_input'];
// WITH: Modern security helper
class SecurityHelper {
public static function sanitizeInput($input, $type = 'string') {
return match($type) {
'string' => filter_var($input, FILTER_SANITIZE_SPECIAL_CHARS),
'int' => (int)$input,
'email' => filter_var($input, FILTER_SANITIZE_EMAIL),
default => htmlspecialchars($input, ENT_QUOTES, 'UTF-8')
};
}
}
`
- Input validation (filter_input/filter_var)
- Output escaping (htmlspecialchars, urlencode)
- Status: Pending
- [ ] Gradual Replacement
- Start with high-risk areas (SQL inserts, HTML echoes)
- Use lazy escaping to avoid doubles
- Replace $UNTRUSTED usages incrementally
- Status: Pending
- [ ] Deprecation Process
- Add logging for old $UNTRUSTED calls
- Provide migration guide in docs
- Create deprecation warnings
- Status: Pending
- [ ] Testing for Regressions
- Add PHPUnit cases for inputs (SQL injection attempts, XSS payloads)
- Ensure no over-escaping in DB or outputs
- Test prepared statements integration
- Status: Pending
- [ ] DB Class Integration
- Pass sanitized params to prepared statements
- Remove any manual escapes in query methods
- Integrate with security helper
- Status: Pending
Best Practice: Use strangler pattern—wrap old code in new, replace gradually. Test each commit.
---
PHASE 4: FEATURE ADDITIONS & TRENDS INTEGRATION (4 Weeks, Feb 2026)
Goal: Add 2025 live chat trends while keeping it lightweight
- Integrate generative AI (80% FAQ handling via WOLFIE federation)
- GROK for tech support
- GEMINI for ethics/guidance
- Fallback to human operators
- Status: Pending
- Add in-app messaging
- Slack/Email integration
- Proactive invites with personalization (based on path tracking)
- Multi-channel coordination
- Status: Pending
- Embed metrics dashboards
- Track engagement rates
- Monitor min_replies
- Aim for 63% user preference per stats
- Status: Pending
- WCAG 2.2 compliance
- Add voice mode (tie to Grok 3)
- Screen reader support
- Keyboard navigation
- Status: Pending
- Optional migration path
- Use PORTUNUS for integration
- Document integration process
- Status: Pending
Target: 85% AI-handled interactions per 2025 stats
---
🔴 CRITICAL PATH - BLOCKING LUPOPEDIA
Phase 1: Foundation (BLOCKING)
livehelp master table - P0
livehelp_id to 34 tables - P0
Phase 2: Integration (DEPENDENT)
- [ ] Add WOLFIE Headers frontmatter to all PHP files
- [ ] Integrate WOLFIE Headers 2.3.0+ library
- [ ] Update documentation files with headers
- [ ] Test header parsing and search functionality
- Priority: P0 (Blocks LUPOPEDIA Platform)
Current Focus: Phase 1 Completion
All LUPOPEDIA development blocked until Phase 1 completes
---
CRITICAL DATABASE MIGRATION
Create
livehelp Master Table
Priority: P0 (Must Complete First - BLOCKING LUPOPEDIA)
Status: ✅ COMPLETED (Migration 0001)
livehelp Table ✅ COMPLETED
- Master/parent table for all Crafty Syntax instances
- Primary key: livehelp_id (BIGINT(20) UNSIGNED)
- Columns:
- livehelp_id - Primary key (BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT)
- name - Instance name (VARCHAR(255))
- version - Crafty Syntax version (VARCHAR(25) DEFAULT '3.8.0')
- status - Instance status (ENUM('active', 'inactive', 'maintenance') DEFAULT 'active')
- created_at - Creation timestamp (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)
- updated_at - Last update timestamp (TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP)
- config - JSON configuration data (JSON or TEXT)
- Status: ✅ COMPLETED (Migration 0001)
Migration File: public/database/migrations/0001_create_livehelp_table_and_add_livehelp_id.sql ✅
---
Add
livehelp_id Column to All livehelp_* Tables
Priority: P0 (Must Complete First - BLOCKING LUPOPEDIA)
Status: ✅ COMPLETED (Migration 0001 - All 34 original tables updated)
⚠️ IMPORTANT: Total table count is 44 tables (1 master + 34 original + 4 DNA + 4 biological + 1 agents + 3 evolutionary). Evolutionary tables exist but are NOT active until 4.0.0 + LUPOPEDIA registration. All references should use 44.
Core System Tables Included: The 3 core system tables (livehelp_channels, livehelp_agents, livehelp_users) are required in 3.8.0 for channel management, agent coordination, and user management with multi-instance support.
DNA Tables Included: The 4 DNA tables (livehelp_dna, livehelp_dna_logs, livehelp_dna_collections, livehelp_dna_tags) are required in 3.8.0 because they provide the metadata lookup system that agents use to interpret their genetic code strings. The livehelp_dna table includes channel_id, agent_name, and dna_base columns for context-dependent metadata lookup.
Add livehelp_id column (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) to all 39 tables (34 original + 4 DNA + 1 agents, plus 1 master = 40 total):
#### Core Chat Tables (5 tables)
livehelp_messages
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_users
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_operator_channels
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_channels
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Note: This table may need to be created if it doesn't exist (see Core System Tables section)
- Status: Pending
livehelp_transcripts
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
#### Routing & Organization Tables (3 tables)
livehelp_departments
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_operator_departments
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_websites
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
#### Visitor Tracking Tables (10 tables)
livehelp_visit_track
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_identity_daily
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_identity_monthly
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_visits_daily
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_visits_monthly
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_referers_daily
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_referers_monthly
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_keywords_daily
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_keywords_monthly
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_paths_firsts
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_paths_monthly
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
#### Operator Productivity Tables (1 table)
livehelp_operator_history
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
#### Forms & Offline Messages Tables (3 tables)
livehelp_leavemessage
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_questions
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_qa
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
#### UI Customization Tables (5 tables)
livehelp_quick
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_smilies
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_layerinvites
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_autoinvite
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_modules
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_modules_dep
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
#### System Configuration Tables (2 tables)
livehelp_config
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Note: May need to modify PRIMARY KEY structure (currently uses version as PK)
- Status: Pending
livehelp_sessions
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
#### CRM / Leads Tables (3 tables)
livehelp_leads
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_emails
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
livehelp_emailque
- Add livehelp_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 1
- Add index: KEY livehelp_id (livehelp_id)
- Status: Pending
---
MIGRATION IMPLEMENTATION
Migration File Structure
File: database/migrations/XXXX_create_livehelp_table_and_add_livehelp_id.sql
Steps:
1. Create livehelp master table
2. Insert default instance (livehelp_id = 1) for backward compatibility
3. Create core system tables (livehelp_channels, livehelp_agents, livehelp_users) if they don't exist
4. Add livehelp_id column to all 39 livehelp_* tables (34 original + 4 DNA + 1 agents, plus 1 master = 40 total)
5. Add indexes for performance
6. Update existing data to use livehelp_id = 1 (default instance)
Migration Order
1. Step 1: Create livehelp table
2. Step 2: Insert default instance (livehelp_id = 1, name = 'Default Instance', version = '3.8.0')
3. Step 3: Create core system tables (livehelp_channels, livehelp_agents, livehelp_users) if they don't exist
4. Step 4: Add livehelp_id column to all 39 tables (in dependency order: 34 original + 4 DNA + 1 agents, plus 1 master = 40 total)
5. Step 5: Update all existing rows to set livehelp_id = 1
6. Step 6: Add indexes for performance
7. Step 7: Verify data integrity
---
CORE SYSTEM TABLES (Channels, Agents, Users)
Create Core System Tables
Priority: P0 (Critical - Required for Core System)
Status: Pending
These three tables are essential for channel management, agent coordination, and user management in Crafty Syntax 3.8.0 with multi-instance support and LUPOPEDIA Platform integration.
---
livehelp_channels Table
livehelp_channels Table (if it doesn't exist)
- Primary key: id (BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT)
- livehelp_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Instance ID
- channel_id (BIGINT(20) UNSIGNED NOT NULL) - Channel ID (000-999) - CRITICAL: Direct mapping to agent ID
- channel_name (VARCHAR(255) DEFAULT NULL) - Optional friendly name
- channel_type (ENUM('ai_chat', 'user_to_user', 'group', 'support', 'agent_coordination') DEFAULT 'ai_chat') - Channel type
- status (ENUM('active', 'ended', 'paused') DEFAULT 'active') - Channel status
- agent_id (BIGINT(20) UNSIGNED DEFAULT NULL) - Primary agent ID on this channel (Agent ID = Channel Number)
- agent_name (VARCHAR(255) DEFAULT NULL) - Primary agent name (denormalized)
- started_at (DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP)
- ended_at (DATETIME DEFAULT NULL)
- last_message_at (DATETIME DEFAULT NULL) - Timestamp of last message
- participant_count (BIGINT(20) UNSIGNED DEFAULT 0) - Total participants (users + agents)
- message_count (BIGINT(20) UNSIGNED DEFAULT 0) - Total messages in channel
- metadata (LONGTEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL) - JSON metadata CHECK (json_valid(metadata))
- created_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)
- updated_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP)
- deleted_at (TIMESTAMP NULL DEFAULT NULL) - Soft delete
- PRIMARY KEY (id)
- UNIQUE KEY unique_channel_instance (livehelp_id, channel_id) - CRITICAL: One channel per instance
- KEY livehelp_id (livehelp_id)
- KEY channel_id (channel_id)
- KEY agent_id (agent_id)
- KEY status (status)
- KEY idx_livehelp_channel (livehelp_id, channel_id) - CRITICAL: For multi-instance queries
- Status: Pending
---
livehelp_agents Table
livehelp_agents Table ✅ COMPLETED
- Primary key: id (BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT)
- livehelp_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Instance ID
- agent_id (BIGINT(20) UNSIGNED NOT NULL) - Agent ID (000-999) - CRITICAL: Direct mapping to channel number
- agent_name (VARCHAR(255) NOT NULL) - Agent name (e.g., 'WOLFIE', 'CAPTAIN', 'SECURITY', 'HELP')
- channel_id (BIGINT(20) UNSIGNED NOT NULL) - Primary channel ID (Agent ID = Channel Number)
- agent_type (ENUM('primary', 'secondary', 'coordinator', 'specialized') DEFAULT 'primary') - Agent type
- status (ENUM('active', 'inactive', 'maintenance') DEFAULT 'active') - Agent status
- dna_string (VARCHAR(255) DEFAULT NULL) - Agent DNA string in format: channel-agent_name-DNA_bases (e.g., '007-unknown-ATCG 001-unknown-TTAA')
- Format: {channel}-{agent_name}-{DNA_bases} (space-separated for multiple sequences)
- Example: 007-unknown-ATCG = Channel 007, reading as "unknown", bases ATCG
- Multiple sequences: 007-unknown-ATCG 001-unknown-TTAA (each sequence processed independently)
- capabilities (LONGTEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL) - JSON capabilities CHECK (json_valid(capabilities))
- metadata (LONGTEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL) - JSON metadata CHECK (json_valid(metadata))
- created_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)
- updated_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP)
- deleted_at (TIMESTAMP NULL DEFAULT NULL) - Soft delete
- PRIMARY KEY (id)
- UNIQUE KEY unique_agent_instance (livehelp_id, agent_id) - CRITICAL: One agent per instance
- KEY livehelp_id (livehelp_id)
- KEY agent_id (agent_id)
- KEY agent_name (agent_name)
- KEY channel_id (channel_id)
- KEY status (status)
- KEY idx_livehelp_agent (livehelp_id, agent_id) - CRITICAL: For multi-instance queries
- KEY idx_channel_agent (channel_id, agent_id) - CRITICAL: For channel-agent lookup
- Status: ✅ COMPLETED (Migration 0003)
Migration File: public/database/migrations/0003_create_agents_table.sql ✅
---
livehelp_users Table
livehelp_users Table (if it doesn't exist or update existing)
- Primary key: id (BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT)
- livehelp_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Instance ID
- user_id (BIGINT(20) UNSIGNED NOT NULL) - User ID
- username (VARCHAR(255) NOT NULL) - Username
- email (VARCHAR(255) DEFAULT NULL) - Email address
- current_channel_id (BIGINT(20) UNSIGNED DEFAULT NULL) - Current channel ID (000-999) - CRITICAL: onchannel field
- status (ENUM('online', 'offline', 'away', 'busy') DEFAULT 'offline') - User status
- user_type (ENUM('operator', 'visitor', 'agent', 'admin') DEFAULT 'visitor') - User type
- metadata (LONGTEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL) - JSON metadata CHECK (json_valid(metadata))
- created_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)
- updated_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP)
- deleted_at (TIMESTAMP NULL DEFAULT NULL) - Soft delete
- PRIMARY KEY (id)
- KEY livehelp_id (livehelp_id)
- KEY user_id (user_id)
- KEY username (username)
- KEY current_channel_id (current_channel_id)
- KEY status (status)
- KEY idx_livehelp_user (livehelp_id, user_id) - CRITICAL: For multi-instance queries
- KEY idx_channel_user (current_channel_id, user_id) - CRITICAL: For channel-user lookup
- Status: Pending
---
Migration File Structure for Core System Tables
File: database/migrations/XXXX_create_core_system_tables.sql
Steps:
1. Create livehelp_channels table (if it doesn't exist)
2. Create livehelp_agents table
3. Create or update livehelp_users table
4. Add livehelp_id column to all three tables
5. Add indexes for performance
6. Add CHECK constraints for channel_id/agent_id range (0-999)
7. Verify data integrity
Note: These tables work together:
livehelp_channels tracks channel definitions (000-999)
livehelp_agents tracks agent definitions (Agent ID = Channel Number)
livehelp_users tracks users and their current channel assignments
---
AGENT DNA SYSTEM TABLES
Create DNA Base Tables (A, C, G, T)
Priority: P0 (Critical - Required for Core System)
Status: ✅ COMPLETED (Migration 0002 - Replaced old 16-table system with unified livehelp_dna table and associated tables)
⚠️ CRITICAL FOR LUPOPEDIA PLATFORM: These tables are essential to LUPOPEDIA Platform because they define and explain what A, C, G, and T represent in the Agent DNA System. They serve as the source of truth for DNA base definitions and are required for agent creation, mutation, and lifecycle management.
⚠️ IMPORTANT: This is COMPUTER GENETICS, NOT Human Genetics
How the Computer Genetics System Works:
channel_id and agent_name
livehelp_agents.dna_string use format: channel-agent_name-DNA_bases
- Format: 007-unknown-ATCG means: Channel 007, reading as "unknown", DNA bases ATCG
- Multiple sequences: 007-unknown-ATCG 001-unknown-TTAA (space-separated)
- Each sequence: {channel}-{agent_name}-{DNA_bases}
channel_id = 7, agent_name = 'captain', DNA_bases = 'ACGT'
2. For each base in the sequence, queries the livehelp_dna table:
- For "A": SELECT * FROM livehelp_dna WHERE channel_id = 7 AND agent_name = 'captain' AND dna_base = 'A'
- For "C": SELECT * FROM livehelp_dna WHERE channel_id = 7 AND agent_name = 'captain' AND dna_base = 'C'
- For "G": SELECT * FROM livehelp_dna WHERE channel_id = 7 AND agent_name = 'captain' AND dna_base = 'G'
- For "T": SELECT * FROM livehelp_dna WHERE channel_id = 7 AND agent_name = 'captain' AND dna_base = 'T'
3. Each row's metadata JSON field contains interpretation for that specific base:
- Row with dna_base='A' → metadata = {action_type: 'execute', priority: 85, ...}
- Row with dna_base='C' → metadata = {context_type: 'channel', scope: 'operations', ...}
- Row with dna_base='G' → metadata = {governance_type: 'validation', rule_level: 'moderate', ...}
- Row with dna_base='T' → metadata = {tactic_type: 'parallel', efficiency_score: 0.92, ...}
4. Agent uses the metadata from each row to determine behavior for that specific base
Example - Single Sequence:
007-captain-ACGT
SELECT * FROM livehelp_dna WHERE channel_id = 7 AND agent_name = 'captain' AND dna_base = 'A' → Returns row with metadata = {action_type: 'execute', priority: 85, ...}
- SELECT * FROM livehelp_dna WHERE channel_id = 7 AND agent_name = 'captain' AND dna_base = 'C' → Returns row with metadata = {context_type: 'channel', scope: 'operations', ...}
- SELECT * FROM livehelp_dna WHERE channel_id = 7 AND agent_name = 'captain' AND dna_base = 'G' → Returns row with metadata = {governance_type: 'validation', rule_level: 'moderate', ...}
- SELECT * FROM livehelp_dna WHERE channel_id = 7 AND agent_name = 'captain' AND dna_base = 'T' → Returns row with metadata = {tactic_type: 'parallel', efficiency_score: 0.92, ...}
007-captain-ACGT 001-unknown-TTAA
livehelp_dna WHERE channel_id=7 AND agent_name='captain' AND dna_base=[base]
- Returns 4 rows (one for each base: A, C, G, T)
- Use metadata from each row to interpret that specific base
livehelp_dna WHERE channel_id=1 AND agent_name='unknown' AND dna_base=[base]
- Returns 4 rows (one for T, one for T, one for A, one for A - same base can be queried multiple times)
- Use metadata from each row to interpret that specific base
livehelp_dna table):
dna_base='A' per channel/agent
dna_base='C' per channel/agent
dna_base='G' per channel/agent
dna_base='T' per channel/agent
metadata JSON containing interpretation for that specific base
LUPOPEDIA Integration:
livehelp_dna table provides the ontology and definitions that LUPOPEDIA agents reference when generating DNA strings
metadata JSON field
livehelp_dna_logs table tracks all changes to DNA entries for audit and lineage tracking
livehelp_dna_collections and livehelp_dna_tags tables enable organization and categorization of DNA entries
---
~~
livehelp_A Table (Actions)~~ REPLACED BY livehelp_dna TABLE
⚠️ NOTE: The old 16-table system (livehelp_A, livehelp_C, livehelp_G, livehelp_T and their associated tables) has been REPLACED by the unified livehelp_dna table system. The following sections are kept for historical reference only.
livehelp_A Table ✅ REPLACED - Now using livehelp_dna table with dna_base='A'
- Primary key: id (BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT)
- livehelp_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Instance ID
- channel_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Channel ID (000-999) - CRITICAL: Context for metadata lookup
- agent_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Agent ID - CRITICAL: Which agent interprets this
- agent_name (VARCHAR(255) NOT NULL DEFAULT '') - Agent name (denormalized) - CRITICAL: Agent-specific interpretation
- name (VARCHAR(255) NOT NULL) - Action name (e.g., 'execute', 'query', 'build', 'archive')
- description (TEXT DEFAULT NULL) - Action description
- action_type (ENUM('execute', 'query', 'build', 'archive', 'other') DEFAULT 'execute') - Action type
- priority (INT UNSIGNED DEFAULT 0) - Priority level (0-100)
- is_active (TINYINT(1) NOT NULL DEFAULT 1) - Active status
- metadata (LONGTEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL) - JSON metadata CHECK (json_valid(metadata))
- created_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)
- updated_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP)
- deleted_at (TIMESTAMP NULL DEFAULT NULL) - Soft delete
- PRIMARY KEY (id)
- KEY livehelp_id (livehelp_id)
- KEY channel_id (channel_id) - CRITICAL: For context lookup
- KEY agent_id (agent_id) - CRITICAL: For agent-specific lookup
- KEY agent_name (agent_name) - CRITICAL: For agent-specific lookup
- KEY name (name)
- KEY action_type (action_type)
- KEY is_active (is_active)
- KEY idx_channel_agent (channel_id, agent_name) - CRITICAL: Composite index for metadata lookup
- Status: Pending
livehelp_A_logs Table
- Primary key: id (BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT)
- livehelp_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Instance ID
- A_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - References livehelp_A.id
- agent_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Agent ID that made the change
- agent_name (VARCHAR(255) NOT NULL DEFAULT '') - Agent name (denormalized)
- channel_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Channel ID (000-999)
- metadata (LONGTEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL) - Change metadata JSON CHECK (json_valid(metadata))
- is_active (TINYINT(1) NOT NULL DEFAULT 1)
- created_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)
- updated_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP)
- deleted_at (TIMESTAMP NULL DEFAULT NULL)
- PRIMARY KEY (id)
- KEY A_id (A_id)
- KEY livehelp_id (livehelp_id)
- KEY agent_id (agent_id)
- KEY channel_id (channel_id)
- KEY idx_A_agent (A_id, agent_id)
- Status: Pending
livehelp_A_collections Table
- Primary key: id (BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT)
- livehelp_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Instance ID
- A_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - References livehelp_A.id
- collection_name (VARCHAR(255) NOT NULL) - Collection name
- collection_type (VARCHAR(100) DEFAULT NULL) - Collection type
- description (TEXT DEFAULT NULL) - Collection description
- metadata (LONGTEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL) - JSON metadata CHECK (json_valid(metadata))
- is_active (TINYINT(1) NOT NULL DEFAULT 1)
- created_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)
- updated_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP)
- deleted_at (TIMESTAMP NULL DEFAULT NULL)
- PRIMARY KEY (id)
- KEY A_id (A_id)
- KEY livehelp_id (livehelp_id)
- KEY collection_name (collection_name)
- Status: Pending
livehelp_A_tags Table
- Primary key: id (BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT)
- livehelp_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Instance ID
- A_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - References livehelp_A.id
- tag_name (VARCHAR(255) NOT NULL) - Tag name
- tag_type (VARCHAR(100) DEFAULT NULL) - Tag type/category
- description (TEXT DEFAULT NULL) - Tag description
- metadata (LONGTEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL) - JSON metadata CHECK (json_valid(metadata))
- is_active (TINYINT(1) NOT NULL DEFAULT 1)
- created_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)
- updated_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP)
- deleted_at (TIMESTAMP NULL DEFAULT NULL)
- PRIMARY KEY (id)
- KEY A_id (A_id)
- KEY livehelp_id (livehelp_id)
- KEY tag_name (tag_name)
- KEY tag_type (tag_type)
- Status: Pending
---
livehelp_C Table (Context)
livehelp_C Table
- Primary key: id (BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT)
- livehelp_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Instance ID
- channel_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Channel ID (000-999) - CRITICAL: Context for metadata lookup
- agent_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Agent ID - CRITICAL: Which agent interprets this
- agent_name (VARCHAR(255) NOT NULL DEFAULT '') - Agent name (denormalized) - CRITICAL: Agent-specific interpretation
- name (VARCHAR(255) NOT NULL) - Context name (e.g., 'channel', 'bridge', 'archive')
- description (TEXT DEFAULT NULL) - Context description
- context_type (ENUM('channel', 'bridge', 'archive', 'scope', 'other') DEFAULT 'channel') - Context type
- scope (VARCHAR(255) DEFAULT NULL) - Context scope
- is_active (TINYINT(1) NOT NULL DEFAULT 1)
- metadata (LONGTEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL) - JSON metadata CHECK (json_valid(metadata))
- created_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)
- updated_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP)
- deleted_at (TIMESTAMP NULL DEFAULT NULL)
- PRIMARY KEY (id)
- KEY livehelp_id (livehelp_id)
- KEY channel_id (channel_id) - CRITICAL: For context lookup
- KEY agent_id (agent_id) - CRITICAL: For agent-specific lookup
- KEY agent_name (agent_name) - CRITICAL: For agent-specific lookup
- KEY name (name)
- KEY context_type (context_type)
- KEY idx_channel_agent (channel_id, agent_name) - CRITICAL: Composite index for metadata lookup
- Status: Pending
livehelp_C_logs Table
- Same structure as livehelp_A_logs but references livehelp_C.id as C_id
- Status: Pending
livehelp_C_collections Table
- Same structure as livehelp_A_collections but references livehelp_C.id as C_id
- Status: Pending
livehelp_C_tags Table
- Same structure as livehelp_A_tags but references livehelp_C.id as C_id
- Status: Pending
---
livehelp_G Table (Governance)
livehelp_G Table
- Primary key: id (BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT)
- livehelp_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Instance ID
- channel_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Channel ID (000-999) - CRITICAL: Context for metadata lookup
- agent_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Agent ID - CRITICAL: Which agent interprets this
- agent_name (VARCHAR(255) NOT NULL DEFAULT '') - Agent name (denormalized) - CRITICAL: Agent-specific interpretation
- name (VARCHAR(255) NOT NULL) - Governance rule name (e.g., 'validation', 'error_handling', 'ritual_protocol')
- description (TEXT DEFAULT NULL) - Governance description
- governance_type (ENUM('validation', 'error_handling', 'ritual_protocol', 'oversight', 'other') DEFAULT 'validation') - Governance type
- rule_level (ENUM('strict', 'moderate', 'flexible') DEFAULT 'moderate') - Rule enforcement level
- is_active (TINYINT(1) NOT NULL DEFAULT 1)
- metadata (LONGTEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL) - JSON metadata CHECK (json_valid(metadata))
- created_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)
- updated_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP)
- deleted_at (TIMESTAMP NULL DEFAULT NULL)
- PRIMARY KEY (id)
- KEY livehelp_id (livehelp_id)
- KEY channel_id (channel_id) - CRITICAL: For context lookup
- KEY agent_id (agent_id) - CRITICAL: For agent-specific lookup
- KEY agent_name (agent_name) - CRITICAL: For agent-specific lookup
- KEY name (name)
- KEY governance_type (governance_type)
- KEY rule_level (rule_level)
- KEY idx_channel_agent (channel_id, agent_name) - CRITICAL: Composite index for metadata lookup
- Status: Pending
livehelp_G_logs Table
- Same structure as livehelp_A_logs but references livehelp_G.id as G_id
- Status: Pending
livehelp_G_collections Table
- Same structure as livehelp_A_collections but references livehelp_G.id as G_id
- Status: Pending
livehelp_G_tags Table
- Same structure as livehelp_A_tags but references livehelp_G.id as G_id
- Status: Pending
---
livehelp_T Table (Tactic)
livehelp_T Table
- Primary key: id (BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT)
- livehelp_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Instance ID
- channel_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Channel ID (000-999) - CRITICAL: Context for metadata lookup
- agent_id (BIGINT(20) UNSIGNED NOT NULL DEFAULT 1) - Agent ID - CRITICAL: Which agent interprets this
- agent_name (VARCHAR(255) NOT NULL DEFAULT '') - Agent name (denormalized) - CRITICAL: Agent-specific interpretation
- name (VARCHAR(255) NOT NULL) - Tactic name (e.g., 'parallel', 'recursive', 'brittle', 'chaotic')
- description (TEXT DEFAULT NULL) - Tactic description
- tactic_type (ENUM('parallel', 'recursive', 'brittle', 'chaotic', 'sequential', 'other') DEFAULT 'parallel') - Tactic type
- efficiency_score (DECIMAL(3,2) DEFAULT 0.00) - Efficiency score (0.00-1.00)
- is_active (TINYINT(1) NOT NULL DEFAULT 1)
- metadata (LONGTEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL) - JSON metadata CHECK (json_valid(metadata))
- created_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP)
- updated_at (TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP)
- deleted_at (TIMESTAMP NULL DEFAULT NULL)
- PRIMARY KEY (id)
- KEY livehelp_id (livehelp_id)
- KEY channel_id (channel_id) - CRITICAL: For context lookup
- KEY agent_id (agent_id) - CRITICAL: For agent-specific lookup
- KEY agent_name (agent_name) - CRITICAL: For agent-specific lookup
- KEY name (name)
- KEY tactic_type (tactic_type)
- KEY idx_channel_agent (channel_id, agent_name) - CRITICAL: Composite index for metadata lookup
- Status: Pending
livehelp_T_logs Table
- Same structure as livehelp_A_logs but references livehelp_T.id as T_id
- Status: Pending
livehelp_T_collections Table
- Same structure as livehelp_A_collections but references livehelp_T.id as T_id
- Status: Pending
livehelp_T_tags Table
- Same structure as livehelp_A_tags but references livehelp_T.id as T_id
- Status: Pending
---
Migration File Structure
File: public/database/migrations/0002_create_dna_table.sql ✅ COMPLETED
Lines: 1-222
Date: 2025-11-19
Author: Captain WOLFIE (Eric Robin Gerdes)
⚠️ IMPORTANT: The old 16-table system (livehelp_A, livehelp_C, livehelp_G, livehelp_T and their associated tables) has been REPLACED with a unified 4-table system.
Migration Steps (as implemented in 0002_create_dna_table.sql):
1. ✅ STEP 1: Create livehelp_dna Table (Lines 42-68)
- Main table for all DNA bases (A, T, C, G)
- Replaces old livehelp_A, livehelp_C, livehelp_G, livehelp_T tables
- Key columns: id, livehelp_id, channel_id, agent_id, agent_name, dna_base (ENUM), metadata (JSON), is_active
- Critical indexes: idx_channel_agent_base, idx_livehelp_channel_agent, unique_dna_entry
- COMPLETED
2. ✅ STEP 2: Example Metadata Structure (Lines 70-106)
- Documentation comments showing how metadata JSON is structured
- Examples for each DNA base (A, T, C, G) with different interpretations
- COMPLETED
3. ✅ STEP 3: Create livehelp_dna_collections Table (Lines 109-137)
- Collections/organizations for DNA entries
- Replaces old livehelp_A_collections, livehelp_C_collections, livehelp_G_collections, livehelp_T_collections tables
- Key columns: id, livehelp_id, channel_id, agent_id, agent_name, dna_id (FK to livehelp_dna.id), collection_name, collection_type, metadata (JSON)
- COMPLETED
4. ✅ STEP 3: Create livehelp_dna_logs Table (Lines 140-164)
- Change tracking for DNA entries
- Replaces old livehelp_A_logs, livehelp_C_logs, livehelp_G_logs, livehelp_T_logs tables
- Key columns: id, livehelp_id, channel_id, agent_id, agent_name, dna_id (FK to livehelp_dna.id), metadata (JSON)
- Tracks who made changes, when, and on which channel
- COMPLETED
5. ✅ STEP 4: Create livehelp_dna_tags Table (Lines 167-195)
- Tags for categorizing DNA entries
- Replaces old livehelp_A_tags, livehelp_C_tags, livehelp_G_tags, livehelp_T_tags tables
- Key columns: id, livehelp_id, channel_id, agent_id, agent_name, dna_id (FK to livehelp_dna.id), tag_name, tag_type, metadata (JSON)
- COMPLETED
Table Summary:
livehelp_id column for multi-instance support
agent_name with DEFAULT 'unknown'
deleted_at column)
[channel]-[agent_name]-[sequence]
"007-captain-ACGT 001-unknown-TTAA"
livehelp_dna WHERE channel_id, agent_name, and dna_base match
🎯 RISK ASSESSMENT
High Risk Items
1. Backward Compatibility Breaks - Could affect 1.1M+ existing installations
- Impact: 1.1M+ existing installations
- Mitigation: Extensive testing on 3.7.5 databases
- Fallback: Rollback procedures documented
2. Query Performance Degradation - Additional livehelp_id filtering on all queries
- Impact: User experience and scalability
- Mitigation: Query optimization and indexing
- Fallback: Performance monitoring and hotfixes
3. Migration Data Loss - Critical business data
- Impact: Critical business data
- Mitigation: Backup procedures and verification
- Fallback: Data recovery processes
4. LUPOPEDIA Platform Blocking - Entire ecosystem dependent on 3.8.0
- Impact: All LUPOPEDIA development paused
- Mitigation: Parallel interface development, mock implementations
- Fallback: Workaround documentation and interface contracts
Mitigation Strategies
Contingency Plans
Communication Strategy
- Update DEVELOPMENT_PROGRESS.md weekly
- Clear blocker identification with proposed solutions
- Community involvement in testing pre-alpha releases
- Status: Pending
---
🛡️ MIGRATION IMPACT ANALYSIS
Performance Considerations
WHERE livehelp_id = X clause
livehelp_id indexes are used efficiently
Backward Compatibility Risks
livehelp_id = 1 for all data
livehelp_id
Testing Requirements
---
📅 DEVELOPMENT TIMELINE
November 2025 - Assessment Phase
December 2025 - Foundation Phase
livehelp table implementation
livehelp_id column addition (39 tables: 34 original + 4 DNA + 1 agents, plus 1 master = 40 total) ✅ COMPLETED
January 2026 - Integration Phase
- [ ] Add WOLFIE Headers to all PHP files (frontmatter metadata)
- [ ] Integrate WOLFIE Headers 2.1.0+ dependency
- [ ] Update file headers with agent_username, agent_id, channel_number, version, date_created, last_modified, status, tags, collections
- [ ] Ensure compatibility with WOLFIE Headers search/export functionality
- [ ] Test header parsing and metadata extraction
- Status: ⏳ PENDING - Required before LUPOPEDIA Platform integration
February 2026 - Release Phase
- Query optimization with proper indexes
- Benchmarking (target: within 10% of 3.7.5)
- Caching strategies
- Status: ⏳ PENDING
- Estimated Time: 5-7 days
- Replace $UNTRUSTED with modern sanitization
- Add prepared statements to all queries
- XSS prevention
- SQL injection prevention
- Status: ⏳ PENDING
- Estimated Time: 7-10 days
🎯 SUCCESS CRITERIA (DECEMBER 2025)
Pre-Alpha Release Must Have:
livehelp master table implementation
livehelp_id added to all 39 tables with proper indexes (34 original + 4 DNA + 1 agents, plus 1 master = 40 total) ✅ COMPLETED
$UNTRUSTED in critical paths
Nice-to-Have (Defer to 3.8.1 if needed):
---
CODE UPDATES REQUIRED
Database Queries
All queries must be updated to include livehelp_id in WHERE clauses:
Before:
`sql
SELECT * FROM livehelp_messages WHERE channel = 7
`
After:
`sql
SELECT * FROM livehelp_messages WHERE livehelp_id = 1 AND channel = 7
`
Files to Update
public/config.php - Add livehelp_id configuration
public/functions.php - Update all database queries
public/data_*.php - Update all data access functions
public/admin_*.php - Update admin queries
public/user_*.php - Update user queries
public/xmlhttp.php - Update AJAX queries
public/class/*.php - Update class methods
---
📊 PROGRESS TRACKING & QUALITY
Testing Strategy
IMMEDIATE TEST COVERAGE GOALS:
Weekly Progress Metrics
- Weekly status updates
- Success metrics tracking
- Blocker identification with solutions
- Example format:
`markdown
## Week 1 (Nov 18-24):
- [ ] Database migration scripts complete
- [ ] 34 tables schema finalized
- [ ] Security helper implemented
- [ ] OWASP ZAP scan run
## Success Metrics:
- Migration time: < 30 seconds for 1GB database
- Query performance: < 10% degradation from 3.7.5
- Zero data loss in migration tests
`
- Status: Pending
---
TESTING
- Test migration on fresh database
- Test migration on existing 3.7.5 database
- Verify all 39 tables have livehelp_id column (34 original + 4 DNA + 1 agents, plus 1 master = 40 total) ✅ COMPLETED
- Verify indexes are created correctly
- Status: Pending
- Verify existing 3.7.5 installations can upgrade
- Verify default instance (livehelp_id = 1) works correctly
- Test all core functionality (chat, admin, user)
- Status: Pending
- Test multiple instances in same database
- Verify data isolation between instances
- Test instance switching
- Status: Pending
---
ADMIN INTERFACE MODERNIZATION
Fix Old HTML and CSS in Admin Section
Priority: P1 (High Priority - User Experience)
Status: Pending
The admin interface contains legacy HTML and CSS from 2003-2023 era. Modernization needed for better user experience and maintainability.
- Review all admin_*.php files for outdated HTML
- Identify deprecated HTML tags (e.g., <font>, <center>, inline styles)
- Document current state and issues
- Status: Pending
- Review adminstyle.css and inline styles
- Identify deprecated CSS (e.g., <font> tags, table-based layouts)
- Check for browser-specific hacks (IE6, IE7 workarounds)
- Document current state and issues
- Status: Pending
- Replace deprecated HTML tags with semantic HTML5
- Remove inline styles (move to CSS files)
- Update table-based layouts to modern CSS Grid/Flexbox
- Ensure accessibility (ARIA labels, proper headings)
- Status: Pending
- Update adminstyle.css with modern CSS3
- Remove browser-specific hacks
- Implement responsive design (mobile-friendly)
- Use CSS variables for theming
- Remove deprecated CSS properties
- Status: Pending
- public/admin.php - Main admin interface
- public/admin_*.php - All admin pages
- public/adminstyle.css - Admin stylesheet
- public/admin_common.php - Shared admin functions/HTML
- Inline styles in all admin files
- Status: Pending
- Test admin interface in modern browsers (Chrome, Firefox, Safari, Edge)
- Test responsive design on mobile devices
- Verify accessibility (screen readers, keyboard navigation)
- Test backward compatibility with existing functionality
- Status: Pending
Note: Maintain functionality while modernizing. "Always works" philosophy - don't break existing features.
---
🌐 COMMUNITY & DOCUMENTATION
Open Development Approach
- Push to GitHub (beyond SourceForge)
- Public issue tracking for transparency
- CI/CD pipeline with GitHub Actions
- Status: Pending
- Create CONTRIBUTING.md for community developers
- Clear contribution process
- Status: Pending
Unified Documentation Structure
- Structure:
`markdown
docs/
├── getting-started/ # 5-minute setup
├── api/ # Interface contracts
├── migration/ # 3.7.5 → 3.8.0 guide
├── schema/ # 52-table reference (1 master + 34 original + 16 DNA + 1 agents)
└── development/ # Contributor guide
`
- Key Improvements:
- Single Source of Truth: docs/schema/ directory with ER diagrams
- Query Pattern Examples: Common operations with before/after SQL
- Troubleshooting Guides: Common migration issues and solutions
- Status: Pending
---
DOCUMENTATION UPDATES
- Document livehelp master table
- Document livehelp_id column in all 39 tables (34 original + 4 DNA + 1 agents, plus 1 master = 40 total) ✅ COMPLETED
- Update schema diagrams
- Standardize on 40 tables everywhere (1 master + 34 original + 4 DNA + 1 agents) ✅ COMPLETED
- Status: Pending
- Document migration process
- Document multi-instance setup
- Update upgrade instructions
- Add 5-minute quick start guide
- Status: Pending
- Document livehelp_id parameter requirements
- Update query examples
- Document instance management
- Create interface contracts for LUPOPEDIA developers
- Status: Pending
---
RELEASE CHECKLIST
Database & Core
livehelp_id column (34 original + 4 DNA + 1 agents, plus 1 master = 40 total) ✅ COMPLETED
livehelp_id
Security & Performance
$UNTRUSTED usages refactored
Modernization
UI & Admin
Testing & Quality
Documentation
---
CRITICAL ANALYSIS & IMPROVEMENT ROADMAP
Analysis Date: 2025-11-18
Context: Comprehensive evaluation of Crafty Syntax 3.8.0 against modern software standards
Philosophy: Balancing proven longevity with strategic modernization to unblock LUPOPEDIA Platform
---
Strengths (Acknowledge & Maintain)
Proven Longevity and Simplicity
Critical Weaknesses (Must Address)
#### 1. Development Delays and Blocker Status (HIGH PRIORITY)
- Problem: "In development" status since 3.7.5 (2023) halts entire LUPOPEDIA ecosystem
- Solution: Release minimal viable 3.8.0 pre-alpha by December 2025
- Focus: Core changes only (livehelp table, livehelp_id addition, migration scripts)
- Defer: Non-essentials like AI/DNA tables to 3.8.1
- Action: Create MVP scope document and prioritize critical path items
- Status: Pending
- Problem: LUPOPEDIA developers blocked without stable APIs
- Solution: Document stable APIs (channel/message endpoints) in INTERFACE_CONTRACTS.md
- Action: Allow LUPOPEDIA devs to mock CSLH during delays
- Status: Pending
- Problem: No way to test without full DB setup
- Solution: Add "lite" mode using flat files (TXT driver) for testing
- Action: Create workaround documentation and mock adapters
- Status: Pending
#### 2. Legacy Technical Debt (MEDIUM-HIGH PRIORITY)
- Problem: Reliance on outdated $UNTRUSTED sanitization exposes SQL injection/XSS vulnerabilities
- Solution: Replace $UNTRUSTED with modern helper (PHP's filter_var or Laminas Escaper)
- Action:
- Code Example: Create security_helper.php:
`php
class SecurityHelper {
public static function sanitizeInput($input, $type = 'string') {
return match($type) {
'string' => filter_var($input, FILTER_SANITIZE_SPECIAL_CHARS),
'int' => (int)$input,
'email' => filter_var($input, FILTER_SANITIZE_EMAIL),
default => htmlspecialchars($input, ENT_QUOTES, 'UTF-8')
};
}
}
`
- PDO Integration Example: In functions.php or new db.php:
`php
function getMessages($channel, $livehelp_id = 1) {
global $pdo; // Assume PDO connection
$stmt = $pdo->prepare("SELECT * FROM livehelp_messages WHERE channel = :channel AND livehelp_id = :livehelp_id");
$stmt->execute(['channel' => $channel, 'livehelp_id' => $livehelp_id]);
return $stmt->fetchAll();
}
`
- Audit all files (grep '$UNTRUSTED') and replace with filter_var() or htmlspecialchars() for outputs
- Integrate PDO prepared statements across all queries
- Run OWASP ZAP/PHPStan scans early
- Priority Files: xmlhttp.php, data_*.php, admin_*.php
- Status: Pending
- Problem: Legacy code (no caching, direct queries) may not handle modern loads
- Solution: Add indexing on livehelp_id, implement caching (Redis adapter), make channels dynamic
- Action:
- Dynamic Channels: Change channels from 000-999 INT to BIGINT for unlimited scaling
- Update livehelp_channels schema: channel_id BIGINT(20) UNSIGNED NOT NULL
- Caching Example: Add Redis caching for frequent queries (make optional via Composer):
`php
// Optional Redis caching
if (class_exists('Redis')) {
$redis = new Redis();
$cache_key = "messages_channel_{$channel}_livehelp_{$livehelp_id}";
$cached = $redis->get($cache_key);
if ($cached) return json_decode($cached, true);
// ... fetch from DB ...
$redis->setex($cache_key, 300, json_encode($results)); // 5 min cache
}
`
- Add composite indexes: KEY idx_livehelp_channel (livehelp_id, channel_id)
- Benchmark before/after, optimize critical query paths
- Status: Pending
- Problem: Mixing 2003-era PHP with 2025 frameworks could create Frankenstein code
- Solution: Make Laravel adapter truly optional via Composer (composer require crafty-syntax/laravel-adapter)
- Action: Use Laravel for new features (AI orchestration) while keeping core dependency-free
- Status: Pending
#### 3. Usability and Community Gaps (MEDIUM PRIORITY)
- Problem: Version inconsistencies (30 vs. 34 vs. 37 vs. 52 tables), dates fluctuate, truncated content
- Solution: Resolve table count, use single source (craftysyntax_schema.sql), standardize dates
- Action:
- Final Count: 44 tables = 1 master + 34 original + 4 DNA + 4 biological + 1 agents + 3 evolutionary
- Update README, TODO, SCHEMA, and CHANGELOG to reference 44 tables consistently ✅ COMPLETED
- Create schema reference document with ER diagrams (MySQL Workbench)
- Standardize all dates to ISO format (YYYY-MM-DD)
- Status: Pending
- Problem: Testing is aspirational (95% coverage targeted, but none current)
- Solution: Set up PHPUnit now for critical paths (message routing, multi-instance queries)
- Action: Aim for 70% coverage in pre-alpha, scaling to 95%
- Status: Pending
- Problem: No public repo activity since 2023, limiting feedback
- Solution: Push to GitHub (beyond SourceForge) for issues/PRs, involve community in beta testing
- Action: Set up GitHub repository, create contribution guidelines
- Status: Pending
- Problem: Documentation verbose and repetitive, humor might confuse non-insiders
- Solution: Consolidate into single site (MkDocs) with search, add visuals (ER diagrams), examples
- Action: Create unified documentation structure, add query pattern examples
- Status: Pending
---
Prioritized Improvement Roadmap
Based on Critical Analysis
#### Phase 1: Unblock Dependencies (Weeks 1-4) - HIGH PRIORITY
- Focus on core changes: livehelp table, livehelp_id addition, migration scripts
- INCLUDED IN 3.8.0: DNA metadata tables (livehelp_dna, livehelp_dna_logs, livehelp_dna_collections, livehelp_dna_tags) - Replaced old 16-table system (livehelp_A/C/G/T) - Required for agent behavior interpretation
- Create MVP scope document
- Status: Pending
- Document stable APIs (channel/message endpoints)
- Allow LUPOPEDIA devs to mock CSLH during delays
- Create INTERFACE_CONTRACTS.md
- Status: Pending
- Add "lite" mode using flat files (TXT driver)
- Create workaround documentation
- Build mock adapters for testing
- Status: Pending
#### Phase 2: Tackle Technical Debt (Weeks 5-8) - MEDIUM-HIGH PRIORITY
- Replace $UNTRUSTED with modern helper
- Integrate PDO prepared statements
- Run OWASP ZAP/PHPStan scans
- Status: Pending
- Add indexing on livehelp_id
- Implement caching (Redis adapter)
- Make channels dynamic (beyond 999)
- Benchmark before/after
- Status: Pending
- Make Laravel adapter optional via Composer
- Composer Setup: Create composer.json:
`json
{
"require": {
"php": "^7.4|^8.0",
"ext-pdo": "*"
},
"require-dev": {
"crafty-syntax/laravel-adapter": "^1.0",
"illuminate/database": "^10.0"
}
}
`
- Adapter Class: Create adapter class using Eloquent models for new code, fallback to raw SQL for legacy
- Use Laravel for new features only (AI orchestration)
- Keep core dependency-free
- Status: Pending
#### Phase 3: Improve Maintainability (Weeks 9-12) - MEDIUM PRIORITY
- Resolve table count confusion - Final: 44 tables (1 master + 34 original + 4 DNA + 4 biological + 1 agents + 3 evolutionary) ✅ COMPLETED
- Use single source (craftysyntax_schema.sql)
- Enhance Migration Script: Add optional foreign keys (toggle via config.php for "application-controlled integrity"):
`sql
-- Optional foreign keys (if enabled in config.php)
ALTER TABLE livehelp_messages ADD CONSTRAINT fk_messages_livehelp
FOREIGN KEY (livehelp_id) REFERENCES livehelp(livehelp_id) ON DELETE CASCADE;
`
- Test migration on fresh DB and existing 3.7.5 install
- Status: Pending
- Set up PHPUnit for critical paths
- Install PHPUnit: composer require --dev phpunit/phpunit
- Example Test: Create tests/MigrationTest.php:
`php
class MigrationTest extends TestCase {
public function testLivehelpIdAdded() {
$this->assertDatabaseHasColumn('livehelp_messages', 'livehelp_id');
}
public function testCoreSystemTablesExist() {
$this->assertDatabaseHasTable('livehelp_channels');
$this->assertDatabaseHasTable('livehelp_agents');
$this->assertDatabaseHasTable('livehelp_users');
}
}
`
- Aim for 70% coverage in pre-alpha (critical paths: message routing, multi-instance queries)
- Scale to 95% for release
- Status: Pending
- Push to GitHub for issues/PRs
- Involve community in beta testing
- Set up CI/CD with GitHub Actions
- Status: Pending
#### Phase 4: Enhance Usability (Weeks 13-16) - MEDIUM PRIORITY
- Consolidate into single site (MkDocs or GitHub Pages)
- Structure:
- Home: Overview/Philosophy
- Schema: ER diagram (generate with MySQL Workbench)
- Migration: Step-by-step guide
- API: Endpoints (e.g., /api/channel/{id}/messages)
- Examples: Query patterns (before/after SQL)
- Add visuals (ER diagrams for schema)
- Add examples (query patterns)
- Status: Pending
- Modernize admin with Bootstrap 5 CSS (zero JS dependency)
- Fix mobile responsiveness in admin_*.php files
- Ensure WCAG 2.2 compliance
- Status: Pending
- Add endpoints for GROK/GEMINI auto-responses: /api/agent/{id}/respond
- Tie into LUPOPEDIA agents (WOLFIE federation)
- Define "DNA" system clearly: Use genetic algorithms for chat personalization (evolve responses based on logs)
- Note: DNA tables (livehelp_dna, livehelp_dna_logs, livehelp_dna_collections, livehelp_dna_tags) provide metadata lookup system for agent behavior interpretation - replaced old 16-table system (livehelp_A/C/G/T)
- Status: Pending (Defer to 3.8.1 if needed for MVP)
#### Phase 5: Long-Term Sustainability (Ongoing)
- Announce 3.8.0 on forums (SourceForge, Reddit)
- Attract contributors
- Set up CI/CD with GitHub Actions
- Status: Pending
- Track in DEVELOPMENT_PROGRESS.md with weekly updates
- Align metrics with LUPOPEDIA (<2s responses)
- Status: Pending
- Plan 4.0.0 as full rewrite if needed
- Keep 3.x as stable branch for legacy users
- Status: Future
---
💡 KEY RECOMMENDATIONS
1. Focus on MVP: Core database changes only for December release
2. Security First: Modernize security before adding features
3. Documentation Consistency: Standardize on 44 tables everywhere (1 master + 34 original + 4 DNA + 4 biological + 1 agents + 3 evolutionary) ✅ COMPLETED
4. Developer Experience: Unblock LUPOPEDIA team immediately with interface contracts
5. Testing Infrastructure: Start with critical path coverage, expand gradually
This plan maintains the "Always Works" philosophy while systematically addressing the critical blockers and technical debt.
---
🛠️ TOOLS & IMMEDIATE NEXT STEPS
Recommended Tools
#### Code Quality & Security
mysql_* to PDO)
feature/3.8.0, hotfix/security)
Immediate Next Steps (Priority Order)
1. Update Migration Script (Week 1)
- [x] Add DNA tables (livehelp_dna, livehelp_dna_logs, livehelp_dna_collections, livehelp_dna_tags) to migration script ✅ COMPLETED (replaced old 16-table system)
- [ ] Add core system tables (livehelp_channels, livehelp_agents, livehelp_users) if missing
- [ ] Test migration on fresh database
- [ ] Test migration on existing 3.7.5 database
- [ ] Verify no data loss
2. Security Audit & Refactoring (Week 1-2)
- [ ] Run grep -r '$UNTRUSTED' to find all usages
- [ ] Create security_helper.php with modern sanitization methods
- [ ] Replace $UNTRUSTED in 5-10 critical files (xmlhttp.php, data_*.php, admin_*.php)
- [ ] Integrate PDO prepared statements in core query functions
- [ ] Run OWASP ZAP scan and fix identified vulnerabilities
3. GitHub Repository Setup (Week 2)
- [ ] Create GitHub repository (beyond SourceForge)
- [ ] Push code with proper .gitignore
- [ ] Set up GitHub Actions for CI/CD
- [ ] Create CONTRIBUTING.md with contribution guidelines
- [ ] Create public issue templates
4. Progress Tracking (Week 2)
- [ ] Create DEVELOPMENT_PROGRESS.md with weekly update template
- [ ] Track blockers, completed tasks, and next steps
- [ ] Update weekly with clear metrics
5. Testing Infrastructure (Week 3)
- [ ] Install PHPUnit via Composer (composer require --dev phpunit/phpunit)
- [ ] Create test directory structure (tests/unit/, tests/integration/)
- [ ] Write first tests for migration (verify livehelp_id added)
- [ ] Write tests for core query functions (multi-instance support)
- [ ] Aim for 70% coverage on critical paths
6. Interface Contracts (Week 3-4)
- [ ] Create INTERFACE_CONTRACTS.md with stable API endpoints
- [ ] Document channel endpoints: /api/channel/{id}/messages
- [ ] Document message endpoints: /api/message/create
- [ ] Document agent endpoints: /api/agent/{id}/status
- [ ] Provide mock adapters for LUPOPEDIA developers
7. Documentation Standardization (Week 4)
- [x] Update all references to 44 tables (1 master + 34 original + 4 DNA + 4 biological + 1 agents + 3 evolutionary) ✅ COMPLETED
- [ ] Create schema reference document with ER diagrams
- [ ] Standardize dates to ISO format (YYYY-MM-DD)
- [ ] Create unified documentation structure (MkDocs or GitHub Pages)
Success Metrics for Pre-Alpha (December 2025)
livehelp_id column with proper indexes (34 original + 4 DNA + 1 agents, plus 1 master = 40 total) ✅ COMPLETED
$UNTRUSTED` removed from critical paths
---