switchboard/core
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Releases 9 Wiki Activity
This repository has been archived on 2026-04-03. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
128cbb8174b2ea7b2fca26cdde2966c4be3b40f3
core/docs/ROADMAP.md
xcaliber 128cbb8174 Changeset 0.28.8 (#194)
2026-03-15 23:43:36 +00:00

15 KiB
Raw Blame History

Roadmap — Chat Switchboard

See also:

  • ARCHITECTURE.md — Core services design, store layer, scope model
  • EXTENSIONS.md — Extension system spec (Browser/Starlark/Sidecar tiers, manifests, browser tool bridge, surfaces/modes, model roles)
  • EXTENSION-SURFACES.md — Extension surface authoring guide (manifest format, platform API, CSS properties, install workflow)
  • CHANGELOG.md — Detailed release notes for all completed versions

Versioning (pre-1.0): 0.<major>.<minor> — hotfixes use quad: 0.x.y.z No compatibility guarantees before 1.0.

Dependency Graph

Two parallel implementation tracks converge at v0.50.0 (MVP). The extension track builds the package ecosystem and workflow capabilities. The operations track builds production readiness for multi-team deployment. Neither blocks the other until the MVP gate.

v0.9.x–v0.28.7  Foundation through Platform Polish          ✅
                 (see CHANGELOG.md for full history)
                        │
                  v0.28.8  ICD Green Board                   ✅
                        │
        ┌───────────────┴───────────────┐
        │                               │
   Extension Track                 Operations Track
        │                               │
   v0.29.0 Starlark Sandbox       v0.32.0 Multi-Replica HA
   v0.29.1 API Extensions         v0.33.0 Observability
   v0.29.2 DB Extensions          v0.34.0 Data Portability
   v0.29.3 Workflow Forms               │
   v0.30.0 Package Lifecycle            │
   v0.30.1 SDK Adoption                 │
   v0.30.2 Workflow Packages            │
   v0.31.0 Editor Package              │
        │                               │
  ══════╪═══════════════════════════════╪══════
        │         MVP v0.50.0           │
        │  (v0.31.0 + v0.34.0          │
        │   + mobile + deployment docs) │
  ══════╪═══════════════════════════════╪══════
        │
   v0.50.0+ Rich Media + Beyond
     (image gen, code sandbox,
      STT/TTS, desktop app)

Target deployment (v0.50.0): 3-node cluster, 3-node PG (patroni/cnpg), S3 (Ceph RGW), CephFS. 5–10 teams × ~5 users, 4 admins, 100+ anonymous visitors. Multi-replica backend for node-level HA.

Completed: v0.28.0 — Platform Polish

Audit arc, frontend decomposition, security, infrastructure. Eight sub-versions, all complete. See CHANGELOG.md for detailed release notes.

Version Summary Key Deliverables
v0.28.1 Surfaces ICD Audit ✅ 6 ICD fixes, 19 E2E tests, 36 Go tests
v0.28.2 ICD Audit: All Domains ✅ 469/469 (100%), full methodology documented
v0.28.3 ICD Close-out + FE Decomp ✅ WebSocket ICD rewrite, 47 JS files → ES modules, sb.js registry
v0.28.4 Security Tier ✅ 58 red-team tests, 5 real bugs found+fixed, JWT role from DB
v0.28.5 Frontend SDK + Pipes ✅ switchboard-sdk.js, 3-stage pipe/filter pipeline, 36 SDK tests
v0.28.6 Infrastructure ✅ Virtual scroll, Helm chart, system tasks, git keygen, broadcast
v0.28.7 Unified Packaging ✅ .pkg format, packages table, task RBAC, task.starlark gate

Deferred from v0.28.x (relocated with version pins):

  • sw.notes() factory → v0.30.1
  • Phase 5 FE decomp (import/export) → v0.30.1
  • Cross-visitor isolation E2E test → v0.29.3
  • Admin UI task permission management → v0.29.0
  • ICD runner packaging test tier → v0.29.0

v0.28.8 — ICD Green Board ✅

Close out pre-existing ICD test failures and infrastructure issues discovered during the green board push.

Depends on: v0.28.7 (unified packaging).

Root cause analysis (discovered during deployment):

The 502/503 cascade that failed 8–10 ICD tests across provider, BYOK, and SDK tiers was caused by OOMKilled — the dev backend pod had a 256Mi memory limit. The Go process peaked at ~216Mi during the 569-test ICD suite and exceeded 256Mi during SSE completion streams, triggering exit code 137. Traefik returned 503 no available server until the pod restarted (~15s).

Memory profile (measured on cluster via kubectl top):

  • 17Mi idle after fresh start
  • 216Mi peak during full ICD suite (569 requests, SSE streams)
  • 60Mi post-test (Go GC ran, heap arena retained)
  • 34Mi settled (~3 min, OS reclaimed freed pages via MADV_DONTNEED)
  • Zero leak — memory returns to baseline, flat steady state

Infrastructure fixes:

  • Backend memory limits: dev/test 128Mi/256Mi → 256Mi/512Mi
  • Batched UpsertFromSync: single transaction, prepared INSERT ON CONFLICT DO UPDATE (300 round-trips → 2, PG + SQLite)
  • DB connection lifecycle: SetConnMaxLifetime(5m) + SetConnMaxIdleTime(1m)
  • HTTP transport pool: sync.Map keyed by proxy config
  • Provider sync timeout: context.WithTimeout(30s), 504 on timeout
  • ICD runner: apiPostRetry, environment-aware CORS test, ticket exchange verification test

Security transport:

  • CORS startup warning, GetAllowedOrigins(), WebSocket CheckOrigin
  • WebSocket ticket exchange: POST /api/v1/ws/ticket, WsAuth middleware, TicketStore with TTL reaper
  • events.js async ticket-first auth with legacy fallback

Kubernetes:

  • Traefik retry Middleware CRD + Helm template
  • RBAC for Gitea runner → traefik.io middleware resources
  • CI non-fatal middleware apply with post-success ingress annotation

Extension Track

Sequential. Each version builds on the previous. Delivers the package ecosystem, workflow capabilities, and SDK-based surface architecture.

v0.29.0 — Starlark Sandbox + Permission Model

Server-side extension runtime. Prove the eval loop, permission pipeline, and admin UI before adding capabilities.

Depends on: v0.28.8.

Phase 0 — Store cleanup (prerequisite):

  • SELECT * → explicit column lists in both store packages
  • Raw SQL hunt: all database.DB.* outside store/ → store methods
  • CI gate: grep-enforced, zero hits

Starlark runtime:

  • go.starlark.net integration (eval loop, timeout, memory ceiling)
  • Permission model: manifest declarations, admin grant/revoke, extension_permissions table
  • Runtime enforcement: sandbox injects only granted modules
  • Admin UI: permission review, grant/revoke, audit log. Task permission management (deferred from v0.28.7).
  • Extension lifecycle: install → pending_review → approved → active
  • Initial modules: secrets (vault-backed), notifications
  • task_type: "starlark": sandbox execution with task context. RBAC gate from v0.28.7 enforced.
  • KB auto-injection: server-side pre-completion filter (Go built-in). Reference implementation for the filter model Starlark mirrors.
  • ICD runner: packaging test tier (deferred from v0.28.7)

v0.29.1 — API Extensions

Starlark route handlers. Surfaces serve custom JSON endpoints.

Depends on: v0.29.0.

  • api_routes manifest key, mounted at /s/{id}/api/...
  • Starlark request/response primitives
  • http outbound module with allowlist/blocklist
  • requires_provider manifest key (provider resolution via BYOK chain)
  • Server-side tool execution in completion handler
  • capability_match routing policy (cheapest model with required caps)
  • Config-file provider types (YAML/JSON, no code deploy)

v0.29.2 — DB Extensions

Namespaced tables for extension data. Create-only (no migrations yet).

Depends on: v0.29.1.

  • ext_{id}_* tables, dialect-correct DDL (PG + SQLite)
  • db Starlark module: query(), exec() scoped to extension tables
  • Views as read contract over platform tables (column allowlist)
  • Schema creation on install, drop on uninstall

v0.29.3 — Workflow Forms

form_template renders as real UI. LLM is optional for data collection.

Depends on: v0.29.2, v0.29.0 (Starlark validators).

  • Typed form_template schema (text, email, select, number, date, textarea, checkbox, file) with validation rules
  • Stage renders as form when form_template has typed fields
  • LLM-optional stages: form-only, form+chat, chat-only
  • Starlark validate / on_submit hooks
  • Visitor form entry (branded page, no chat widget)
  • Form builder in workflow admin (visual field editor)
  • Cross-visitor isolation E2E test (deferred from v0.28.4)

v0.30.0 — Package Lifecycle

Lifecycle sophistication for .pkg format.

Depends on: v0.29.2.

  • Schema versioning + migrations in manifest
  • Settings extension point (packages declare settings sections)
  • Export/import format for cross-instance sharing
  • Package marketplace (discovery, not hosting)
  • User-installable packages (RBAC-gated, team/personal scope)

v0.30.1 — SDK Adoption

Migrate core surfaces to sw.* SDK.

Depends on: v0.28.5, v0.30.0.

  • sw.notes(), sw.chat(), sw.panels() real factories
  • Core surface migration: chat, editor, notes, settings
  • Phase 5 FE decomp: import/export statements
  • Memory compaction: summarize, confidence decay, prune

v0.30.2 — Workflow Packages

Workflows as installable packages. Visual builder for team admins.

Depends on: v0.29.3, v0.30.0, v0.30.1.

  • Stage surfaces: form, chat, review, custom .pkg
  • .pkg type "workflow" bundles definition + surfaces + handlers
  • Team admin workflow builder (visual, no JSON editing)
  • sw.workflow SDK namespace

v0.31.0 — Editor Package

E2E proof: rebuild editor as installable .pkg. Zero platform special-casing. Validates the full v0.28.7–v0.30.2 stack.

Depends on: v0.30.2.

  • Editor .pkg (type: full), settings via extension point
  • State persistence via ext_editor_* tables
  • Remove editor from core (surface-editor template, data loader)

Operations Track

Parallel to extension track. No Starlark dependency. Delivers production readiness for the target multi-team deployment.

v0.32.0 — Multi-Replica HA

Run 2–3 backend replicas across nodes for node-level availability.

Depends on: v0.28.8.

What already works multi-replica:

  • REST API (stateless, JWT auth) ✅
  • PG + S3 + CephFS (shared infrastructure) ✅
  • pg_broadcast LISTEN/NOTIFY (cross-pod event bus) ✅

What needs work:

  • WebSocket fan-out: wire Bus.Subscribe to pg_broadcast listener so events from other pods reach local WebSocket connections. LISTEN/NOTIFY plumbing exists — bridge inbound NOTIFY into per-pod hub for local delivery.
  • Task scheduler leader election: Kubernetes Lease-based. Only leader runs cron scheduler. Prevents duplicate execution.
  • Shared ticket store: TicketStore from sync.Map → PG table with 30s TTL. Ensures WS ticket from pod-1 validates on pod-2.
  • Shared rate limiter: in-memory → PG or Redis counter. Without this, effective rate limit = N × configured across N replicas.
  • Health check refinement: readiness probe fails fast on PG connection loss.
  • Helm: backend.replicaCount > 1 tested. Pod anti-affinity to spread across nodes.

Sizing (measured on v0.28.8):

Metric Value
Idle memory 17Mi
Peak (569 reqs, 4 users, SSE) 216Mi
Settled after GC 34Mi
Per-SSE stream ~500KB–1MB
Per-WebSocket ~64KB
DB pool 25 max (shared)

v0.33.0 — Observability

Metrics, dashboards, alerting. Operate the platform without reading Go source code.

Depends on: v0.32.0 (multi-replica metrics aggregation).

  • Prometheus /metrics endpoint: request latency, active WebSocket gauge, completion token counters, DB pool stats, provider health
  • Grafana dashboard template: system overview, per-team usage, provider latency, error rates
  • Structured logging: LOG_FORMAT=json, request ID propagation, correlation IDs in completion chains
  • Alerting rules: OOM recovery, provider down, pool exhaustion, task failure rate
  • Admin dashboard surface: real-time health (built-in, no Grafana)

v0.34.0 — Data Portability

Export, import, backup, compliance.

Depends on: v0.29.2 (DB extensions — extension data in exports).

  • Bulk export/import: account data, conversations, settings, files
  • GDPR "download my data" + "delete my data" (cascade + audit trail)
  • ChatGPT/other tool import (conversation format mapping)
  • Backup/restore CronJob manifests for K8s
  • Admin export: team/user config (excludes vault-encrypted keys)

MVP v0.50.0

Gate: deploy for 5–10 teams, ~50 users, 100+ anonymous visitors on a 3-node cluster. An IT team can operate the platform without reading Go source code. Team admins build workflows visually.

Requires all of:

  • Extension track through v0.31.0 (full package ecosystem, visual workflow builder, SDK-based surfaces, editor package proving E2E)
  • Operations track through v0.34.0 (multi-replica HA, observability, data portability)

Additionally requires:

  • Deployment guide: step-by-step for IT team (PG cluster, S3/MinIO, CephFS/NFS, Helm install, TLS, OIDC)
  • Admin guide: team setup, provider config, workflow creation, package management, backup/restore
  • Mobile-responsive layouts (proper mobile navigation, touch-optimized chat, not just CSS responsive)
  • Project creation dialog (replace prompt() with modal)
  • Admin-level project management (cross-instance visibility)

v0.50.0+ — Rich Media + Beyond

Post-MVP. Each item is a standalone .pkg or platform primitive. No ordering constraints between items.

Media + Generation

  • Image generation tool (browser or sidecar, provider-agnostic)
  • STT input (browser extension, Web Speech API)
  • TTS output (browser extension, provider API)
  • Code execution sandbox (server-side, container isolation)

Desktop + Mobile

  • Desktop app (Tauri — native wrapper around existing web UI)
  • Full PWA with offline capability

Platform

  • Multi-tenant SaaS mode (tenant isolation, billing, onboarding)
  • Surface IDE (built-in surface for building surfaces)
  • Sidecar HTTP tool protocol (container-isolated tool execution)
  • Latency-aware provider routing (response time percentiles)
  • Cost-aware routing with budget ceiling per request
  • Fallback chain visualizer (drag-to-reorder provider priority)

Knowledge + Memory

  • Hybrid KB search (vector + tsvector + re-rank)
  • Semantic chunking (embedding-based boundary detection)
  • HNSW index (replaces IVFFlat for large datasets)
  • Web scraping KB source (ingest URLs via url_fetch)
  • Scheduled re-indexing (periodic rebuild when sources update)
  • Memory export/import (portable format across instances)
  • Cross-persona memory sharing (opt-in)
  • Memory analytics dashboard

Projects

  • /p/:id shared project view
  • Project-specific file uploads (own endpoint, storage path)
  • Project templates (predefined configurations)
  • Sub-projects / nested hierarchy

UX

  • "Group" scope badge on model selector / KB list
  • Article drag-to-reorder outline sections
  • Article AI tools (suggest_outline, expand_section, check_citations)
  • Rate limiting per user/team/tier (token budgets)
Reference in New Issue View Git Blame Copy Permalink