Current

Codebase Alignment Specification

Status: Active alignment plan
Date: July 12, 2026
Authority: Nirmal (Founder)
Canonical Reference: CANONICAL_PLATFORM_ARCHITECTURE.md
Purpose: Maps current services to canonical Platform Planes and defines alignment actions

Current State

The codebase has 30 services in services/. The canonical architecture defines 18 Platform Planes. There is a significant mismatch that needs resolution.

Service → Plane Mapping

Direct Mappings (Service exists and maps to a Plane)

Current ServiceCanonical PlaneWrangler NameStatus
pipelinePipelineintegratewise-pipeline✅ Maps
connectorIntegration Manager (API Connector)connector✅ Maps
mcp-connectorIntegration Manager (MCP)integratewise-mcp-connector✅ Maps
intelligenceIntegration Manager (AI Connector)intelligence✅ Maps
knowledgeKnowledgeknowledge✅ Maps
continuityContinuity Pipelinecontinuity✅ Maps
hermesHermesintegratewise-hermes✅ Maps
governGovernance Engineintegratewise-govern✅ Maps
storeAdaptive Spineintegratewise-store⚠️ Partial (Spine only, not Cache/Blobs)
thinkTwin (reasoning)integratewise-think⚠️ Partial
iw-agent-runtimeTwin (runtime)iw-agent-runtime⚠️ Partial
twin-orchestratorTwin (orchestration)twin-orchestrator⚠️ Partial

Services Requiring Renaming/Consolidation

Current ServiceTarget PlaneAction Required
loaderPipelineConsolidate into pipeline
normalizerPipelineConsolidate into pipeline
actHermes (execution)Consolidate into hermes or rename to execution
connector-syncSync EngineRename to sync-engine
webhook-ingressIntegration ManagerConsolidate into connector or rename
agent-registryCapability FabricRename to capability-fabric
workflowCapability FabricConsolidate into capability-fabric

Services That Are Cross-Cutting Infrastructure

Current ServiceInfrastructure LayerAction Required
gatewayIdentity + Secrets, Queues + EventsKeep as-is (cross-cutting)
adminAdmin + OperationsKeep as-is (cross-cutting)
billingBilling + EntitlementsKeep as-is (cross-cutting)
telemetryObservabilityKeep as-is (cross-cutting)
tenantsConfiguration Manager (partial)Keep or consolidate into config-manager
signalsQueues + EventsKeep or consolidate into events

Services That Are Legacy/Unknown

Current ServiceAssessmentAction Required
l2Legacy overlay schemaEvaluate for retirement
core-engineUnknown purposeEvaluate for retirement or consolidation
folder-watcherFile monitoringEvaluate for consolidation into connector
huggingface-inferenceModel inferenceEvaluate for consolidation into intelligence
schema-aiSchema managementEvaluate for consolidation into config-manager or knowledge

Canonical Planes Missing Services

Canonical PlaneCurrent ServiceAction Required
Configuration Managertenants (partial), schema-ai (partial)Create new config-manager service
Activation BridgeNoneCreate new activation-bridge service
Spine CacheNone (part of store)Extract from store or create new service
BlobsNone (part of store)Extract from store or create new service
User Workbenchapps/live (frontend)Frontend only, no service needed
Twin MemoryNone (part of iw-agent-runtime)Extract from iw-agent-runtime or create new service
Session LogsNone (part of iw-agent-runtime)Extract from iw-agent-runtime or create new service
Twin Audit LogsNone (part of iw-agent-runtime)Extract from iw-agent-runtime or create new service
Sync Engineconnector-sync (partial)Rename and expand connector-sync

Target State

After alignment, the services should map to:

Platform Plane Services (18)

ServiceCanonical PlaneWrangler Name
config-managerConfiguration Managerintegratewise-config-manager
integration-managerIntegration Managerintegratewise-integration-manager
activation-bridgeActivation Bridgeintegratewise-activation-bridge
pipelinePipelineintegratewise-pipeline
spineAdaptive Spineintegratewise-spine
spine-cacheSpine Cacheintegratewise-spine-cache
knowledgeKnowledgeintegratewise-knowledge
blobsBlobsintegratewise-blobs
twinTwinintegratewise-twin
twin-memoryTwin Memoryintegratewise-twin-memory
session-logsSession Logsintegratewise-session-logs
twin-audit-logsTwin Audit Logsintegratewise-twin-audit-logs
capability-fabricCapability Fabricintegratewise-capability-fabric
governance-engineGovernance Engineintegratewise-governance-engine
hermesHermesintegratewise-hermes
sync-engineSync Engineintegratewise-sync-engine
continuity-pipelineContinuity Pipelineintegratewise-continuity-pipeline

Cross-Cutting Infrastructure Services (8)

ServiceInfrastructure LayerWrangler Name
gatewayIdentity + Secrets, Queues + Eventsgateway
adminAdmin + Operationsintegratewise-admin
billingBilling + Entitlementsintegratewise-billing
telemetryObservabilityintegratewise-telemetry
tenantsConfig Stateintegratewise-tenants
eventsQueues + Eventsintegratewise-events
secretsIdentity + Secretsintegratewise-secrets
deploymentDeployment + Runtimeintegratewise-deployment

Frontend Apps (unchanged)

AppPurpose
apps/liveUser Workbench (primary)
apps/webLegacy/marketing
apps/mobileMobile app
apps/desktopDesktop app
apps/workspaceInternal workspace
apps/docsDocumentation

Alignment Actions

Phase 1: Consolidation (Reduce service count)

  1. Consolidate Pipeline services: Merge loader + normalizer into pipeline
  2. Consolidate Twin services: Merge think + iw-agent-runtime + twin-orchestrator into twin
  3. Consolidate Capability Fabric: Merge agent-registry + workflow into capability-fabric
  4. Rename Sync Engine: Rename connector-sync to sync-engine

Phase 2: Creation (Fill gaps)

  1. Create config-manager from tenants + schema-ai
  2. Create activation-bridge (new service)
  3. Extract spine-cache from store
  4. Extract blobs from store
  5. Extract twin-memory from iw-agent-runtime
  6. Extract session-logs from iw-agent-runtime
  7. Extract twin-audit-logs from iw-agent-runtime

Phase 3: Retirement (Remove legacy)

  1. Evaluate l2 for retirement
  2. Evaluate core-engine for retirement or consolidation
  3. Evaluate folder-watcher for consolidation into connector
  4. Evaluate huggingface-inference for consolidation into intelligence
  5. Evaluate webhook-ingress for consolidation into connector

Phase 4: Rename (Align names)

  1. Rename store to spine
  2. Rename connector to integration-manager
  3. Rename mcp-connector (part of integration-manager)
  4. Rename intelligence to ai-connector
  5. Rename govern to governance-engine

Priority Order

  1. P0: Consolidate Pipeline (loader + normalizer → pipeline)
  2. P0: Consolidate Twin (think + iw-agent-runtime + twin-orchestrator → twin)
  3. P0: Rename store → spine
  4. P1: Create config-manager from tenants + schema-ai
  5. P1: Create activation-bridge (new)
  6. P1: Rename connector-sync → sync-engine
  7. P2: Extract spine-cache, blobs from store
  8. P2: Extract twin-memory, session-logs, twin-audit-logs from iw-agent-runtime
  9. P2: Consolidate capability-fabric from agent-registry + workflow
  10. P3: Evaluate and retire legacy services

Verification Criteria

After alignment, verify:

  1. Every canonical Plane has a corresponding service
  2. No service exists without a canonical Plane mapping
  3. All wrangler.toml names follow the pattern integratewise-{plane-name}
  4. All services have consistent TypeScript types matching the canonical data models
  5. All services have consistent API contracts matching the canonical execution sequences
  6. Frontend components reference the correct service names
  7. Deploy scripts reference the correct service names
  8. Documentation references the correct service names