rdmbair15m5-changelog-20260911-0353-ecsai-milestone-m2-engine

Implement Milestone M2 (Features 13–18 in PROJECT.md): Unified Local & Multi-Provider LLM Client Engine (ECSAI).

Scope

• Canonical packages on rdmsm4x:
  • ~/dev/lib/ECSAI (standalone package)
  • ~/dev/lib/ecs0lib (monolithic umbrella package)
• Dual-surface parity: 100% byte-for-byte synchronization between ECSAI/Sources/ECSAI/ and ecs0lib/Sources/ECS0AI/.

Exact Files Added & Modified

• rdmsm4x:~/dev/lib/ECSAI/Sources/ECSAI/SecretKey.swift
  • Sendable zero-leak wrapper with private reference-counted Storage class.
  • Deallocation memory zeroing via Darwin memset_s(ptr, count, 0, count).
  • Redaction across CustomStringConvertible, CustomDebugStringConvertible, CustomReflectable, and Encodable returning "[REDACTED_SECRET: Ref ...]" (or "[REDACTED_SECRET]").
  • Scoped accessors: withUnsafeBytes, exposeSecret, revealSecurely(), and zeroize().
  • Constant-time equality comparison using Darwin timingsafe_bcmp.
• rdmsm4x:~/dev/lib/ECSAI/Sources/ECSAI/CredentialResolver.swift
  • 4-Tier Credential Resolution:
    • Tier 1: Explicit parameter (explicitKey).
    • Tier 2: macOS Keychain non-interactive query (SecItemCopyMatching with kSecUseAuthenticationContext and LAContext().interactionNotAllowed = true).
    • Tier 3: Global environment file ~/.secrets/global.env safe line-by-line parser enforcing POSIX mode 0600 (st_mode & 0o777 == 0o600), throwing CredentialResolutionError.insecureFilePermissions if mode != 0600.
    • Tier 4: Process environment (ProcessInfo.processInfo.environment).
    • Fallback: (nil, .unresolved).
• rdmsm4x:~/dev/lib/ECSAI/Sources/ECSAI/LLMModels.swift
  • LLMMessageRole (.system, .user, .assistant, .tool).
  • LLMMessage with convenient initializers and role factories.
  • LLMOptions with temperature clamped to [0.0, 2.0], maxTokens, stopSequences, tools, apiKey, customHeaders, and timeoutInterval.
  • LLMUsage, LLMResponse, LLMStreamDelta (supporting both token text and typed event streaming), LLMToolDefinition, LLMToolCall, LLMToolCallResponse.
  • LLMError hierarchy covering invalidEndpoint, invalidRequest, invalidResponse, httpError, rateLimitExceeded, contextLengthExceeded, modelNotFound, offlineDaemonConnectionRefused, serviceUnavailable, metalOOM, unsupportedArchitecture, emptyMessages.
• rdmsm4x:~/dev/lib/ECSAI/Sources/ECSAI/LLMProtocols.swift
  • LLMProvider protocol: generateText, streamText, chat, streamChat, generateEmbeddings, callTools.
• rdmsm4x:~/dev/lib/ECSAI/Sources/ECSAI/OllamaConnector.swift
  • Native local AI connector interfacing with local Ollama daemons over loopback (127.0.0.1:11434, Rule 23 compliant).
  • Endpoints: /api/generate, /api/chat, /api/embeddings, /api/tags.
  • NDJSON streaming with line-by-line decoding.
• rdmsm4x:~/dev/lib/ECSAI/Sources/ECSAI/AppleMLXConnector.swift
  • Apple Silicon Metal backend specification (AppleMetalBNNS).
  • Architecture guard (#if arch(arm64)), OpenAI server bridge, and Metal OOM error mapping.
• rdmsm4x:~/dev/lib/ECSAI/Sources/ECSAI/LlamaCppConnector.swift
  • Loopback /v1/chat/completions with SSE delta streaming.
  • Handles maxTokens == 0 length finish reason and 503 service unavailable mapping.
• rdmsm4x:~/dev/lib/ECSAI/Sources/ECSAI/OpenAICompatibleEngine.swift
  • Shared core engine powering OpenAIProvider, GroqProvider, OpenRouterProvider, MistralProvider, and XAIProvider.
  • SSE delta streaming and tool calling reassembly.
• rdmsm4x:~/dev/lib/ECSAI/Sources/ECSAI/ClaudeProvider.swift
  • Anthropic Messages API connector with system prompt extraction and typed SSE event parsing (content_block_delta, message_delta, message_stop).
• rdmsm4x:~/dev/lib/ECSAI/Sources/ECSAI/GeminiProvider.swift
  • Google Gemini v1beta API connector with x-goog-api-key header authentication and contents/parts structure.
• rdmsm4x:~/dev/lib/ECSAI/Sources/ECSAI/LLMProviderFactory.swift
  • Provider resolution across all 10 provider IDs.
• rdmsm4x:~/dev/lib/ECSAI/Tests/ECSAITests/
  • MockURLProtocol.swift
  • SecretKeyTests.swift (9 tests)
  • CredentialResolverTests.swift (7 tests)
  • LocalAIConnectorTests.swift (10 tests)
  • CloudAIConnectorTests.swift (9 tests)
  • ECSAITests.swift (8 baseline tests)
• rdmsm4x:~/dev/lib/ecs0lib/Sources/ECS0AI/
  • Mirrored all 11 source files from ECSAI/Sources/ECSAI/ with 0 diff lines.
• rdmsm4x:~/dev/lib/ecs0lib/Tests/ECS0LibTests/ECSAITests.swift
  • Unit tests covering ECS0AI in the umbrella test suite.

Verification Commands & Evidence

1. Standalone Package Tests: ssh rdmsm4x 'swift test --package-path ~/dev/lib/ECSAI' Result: 43/43 tests passed in 0.016s with 0 warnings under .swiftLanguageModes: [.v6].
2. Umbrella Package Tests: ssh rdmsm4x 'swift test --package-path ~/dev/lib/ecs0lib --filter ECS0AITests' Result: 6/6 tests passed in 0.008s.
3. Umbrella Baseline Regression Check: ssh rdmsm4x 'swift test --package-path ~/dev/lib/ecs0lib --filter Tier1_FeatureCoverageTests/testAI' Result: 6/6 tests passed in 0.027s.
4. Universal Binary Compilation: ssh rdmsm4x 'swift build --package-path ~/dev/lib/ECSAI -c release --arch arm64 --arch x86_64' Result: Built universal release binary with both slices.
5. Independent 4-Tier E2E Test Suite: /Users/richh/teamwork_projects/ecslibrary_expansion/tests/e2e/run_e2e_tests.zsh Result: 392/392 tests passed (100.00%) in 4.14s.

Local Git Commits on rdmsm4x

• ECSAI: 0568684 feat(ECSAI): implement Milestone M2 unified local and cloud LLM client engine (Features 13-18)
• ecs0lib: ded9b59 feat(umbrella): mirror Milestone M2 ECSAI local and cloud LLM client engine into ECS0AI (Features 13-18)

Rollback / Undo

• git -C ~/dev/lib/ECSAI reset --hard HEAD~1
• git -C ~/dev/lib/ecs0lib reset --hard HEAD~1