core/docs/ROADMAP.md

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 + SDK     ✅         │
   v0.31.1 SDK Exercise     ✅         │
   v0.31.2 Team Workflows   ✅         │
        │                               │
        │                          v0.35.0 Workflow Product
        │                               │
  ══════╪═══════════════════════════════╪══════
        │         MVP v0.50.0           │
        │  (v0.31.2 + v0.35.0          │
        │   + mobile + deployment docs) │
  ══════╪═══════════════════════════════╪══════
        │
   v0.50.0+ Rich Media + Beyond
     (image gen, code sandbox,
      STT/TTS, desktop app)

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. Eval loop, permission pipeline, pre-completion filter chain, and admin review workflow.

Depends on: v0.28.8.

Phase 0 — Store cleanup (prerequisite): ✅

• Raw SQL hunt: all ~242 database.DB.* calls outside store/ migrated to store interface methods (CS0–CS7b, 12 changesets)
• CI green on both PG and SQLite pipelines
• ICD runner: 579/580 pass, 1 expected skip
• Documented exception: events/pg_broadcast.go (pg_notify, PG-only, no store abstraction needed)

Phase 1 — Starlark runtime: ✅

• Pre-completion filter chain: composable PreCompletionFilter interface + Chain registry. KB auto-inject refactored as first built-in filter. Extension filters register at order 100+ (CS0)
• go.starlark.net integration: sandboxed eval with step limits (1M ops default), context timeout, captured print output, disabled load(). MakeModule helper for Go→Starlark (CS1)
• Permission model: extension_permissions table (in 016), status column on packages (active/pending_review/ suspended). Manifest "permissions" array parsed on install. Admin review, grant, revoke, grant-all endpoints (CS2)
• Runtime enforcement: Runner.buildModules() injects only granted modules into sandbox namespace (CS3)
• Extension lifecycle: install → pending_review → grant-all → active, revoke → suspended. Auto-transitions on grant/revoke.
• Initial modules: secrets (GlobalConfig-backed, per-package key-value store, admin CRUD), notifications (wraps notification service, send(user_id, title, body?, type?)) (CS3)
• task_type: "starlark": executor executeStarlark loads package by ID, calls on_run() entry point via runner. RBAC gate task.starlark enforced. system_function field holds package ID (CS4)
• KB auto-injection: server-side pre-completion filter chain. Reference implementation for the filter model Starlark extensions mirror via on_pre_completion(ctx) (CS0+CS3)
• Starlark filter discovery: DiscoverStarlarkFilters scans active packages with filters.pre_completion grant (CS3)
• ICD runner: packaging test tier — 18 tests covering permission lifecycle + secrets CRUD (CS5)

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)
• capability_match routing policy (cheapest model with required caps)
• Config-file provider types (JSON, no code deploy)

Deferred to v0.29.2:

• Server-side tool execution in completion handler (requires tool registry integration with sandbox; aligns with DB extensions scope)

v0.29.2 — DB Extensions ✅

Namespaced tables for extension data. Structured API, not raw SQL. Server-side tool execution (deferred from v0.29.1) included.

Depends on: v0.29.1.

• ext_{id}_* tables, dialect-correct DDL (PG + SQLite)
• db Starlark module: structured query/insert/update/delete/list_tables/view (structured API instead of raw exec() — prevents SQL injection)
• Views as read contract over platform tables (ext_view_users, ext_view_channels)
• Schema creation on install, drop on uninstall
• Server-side tool execution in completion handler (deferred from v0.29.1)

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
• ICD test fixes (auth rate limiter burst 30→8, vault UEK pre-warm)
• Starlark workflow.* module (get_definition, get_stage_data, advance, reject)
• Workflow package export/import (.pkg round-trip)
• E2E tests: export/import, surface_pkg_id persistence

v0.31.0 — Editor Package + SDK Composability ✅

E2E proof: rebuild editor as installable .pkg. Zero platform special-casing. Full SDK composability — every UI piece created through sw.* factories, no component duplication.

Depends on: v0.30.2.

Editor Package (CS0–CS2):

• Editor .pkg (type: full), settings via extension point
• State persistence via localStorage (per-user, per-workspace UI state)
• Remove editor from core (surface-editor template, data loader)
• E2E tests: install, settings, export/import round-trip, core removal
• Self-mounting components (Component.mount() is canonical entry point)

SDK Composability (CS3–CS4):

• Delete NoteEditor — NotePanel is single canonical notes component
• Platform scripts in base.html (chat-pane, note-panel, note-graph available to all surfaces)
• UserMenu.mount() — self-contained, works in any container
• sw.userMenu() — mount user menu anywhere, flyout: 'up'|'down'
• sw.chat() uses ChatPane.mount() (not manual DOM + .create())
• sw.fileTree(), sw.codeEditor(), sw.layout() SDK wrappers
• sw.menu(), sw.dropdown(), sw.toolbar(), sw.tabs() UI primitives
• --bg-elevated / --border-elevated CSS tokens for floating panels
• Editor package uses SDK exclusively (sw.layout, sw.fileTree, sw.codeEditor, sw.chat, sw.notes, sw.userMenu)
• Nginx caching: JS/CSS use must-revalidate (not immutable) for dev reload safety
• NotePanel: pagination, select mode, sticky selection bar, note-panel-root class (no PanelRegistry conflict)

Known remaining (visual polish, not blocking):

• UserMenu flyout contrast on very dark backgrounds — fixed in v0.31.1 CS0+CS1
• Editor chat pane duplicates streaming/model-selector logic — absorbed into ChatPane in v0.31.1 CS2

v0.31.1 — SDK Exercise Surface ✅

Build a dashboard surface package exercising every sw.* primitive with zero component CSS overrides. Fix 4 SDK bugs first.

Depends on: v0.31.0.

SDK Bug Fixes (CS0–CS2):

• Flyout unification — 3 competing CSS systems consolidated into .sw-menu-flyout in primitives.css
• Flyout positioning — position:fixed escape hatch for overflow-clipped extension surfaces
• Menu unification — UserMenu uses .sw-menu-flyout + data-position, same as sw.menu()
• ChatPane self-contained — standalone mode with streaming, model selector, history (editor slimmed ~220 lines)

Dashboard Package (CS3–CS4):

• packages/dashboard/ — type "full", route /s/dashboard
• Exercises all 14 primitives: userMenu, menu, toolbar, tabs, dropdown, chat, notes, modal, confirm, toast, on/emit, api, user/isAdmin, theme
• Layout-only CSS — zero references to SDK component classes
• E2E tests: install, settings, export/import round-trip (7 tests)

v0.31.2 — Team Workflow Self-Service ✅

Close the gap: team admins can create and manage workflows for their team without requiring platform admin access. Clean public URLs via team slugs (/w/engineering/intake).

Depends on: v0.31.1.

CS0 — Backend: Team-Scoped Workflow Routes + Team Slugs:

• /teams/:teamId/workflows route group behind RequireTeamAdmin
• CRUD: GET (list), POST (create, inject team_id), PATCH (update), DELETE
• Stage CRUD: GET, POST, PUT, DELETE, PATCH reorder — scoped to team workflows
• Publish: POST /teams/:teamId/workflows/:id/publish
• Ownership guard: all mutating ops verify workflow.team_id == :teamId
• Reuse existing WorkflowHandler methods — team ID injection, not new logic
• Team slug column — auto-generated from name, UNIQUE, GetBySlug store method
• Workflow entry + page renderer resolve scope via team slug (UUID fallback)
• Auth rate limiter burst 8→5

CS1 — Frontend: Workflows Tab in Team Admin:

• 9th tab "Workflows" in team admin modal
• List team workflows with status badge (active/inactive)
• Create/edit workflow form (name, slug, entry_mode, branding, retention)
• Stage builder (add/reorder/delete stages, persona picker, history_mode)
• Publish button with version display
• Adapted from platform admin workflow UI (_loadAdminWorkflows reference)
• Public URL display uses team slug (/w/engineering/intake)
• ICD runner: team workflow CRUD tests, package settings fix, SSE reasoning_content fix

Future (not blocking):

• Team admin modal → full surface package (when tab count justifies it)

---

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.

Design decision: PG SKIP LOCKED replaces Kubernetes Lease-based leader election. Every replica runs the scheduler poll loop; PG serializes task claims atomically. No K8s API dependency, no Redis, no new coordination infrastructure. See docs/DESIGN-0.32.0.md.

What already works multi-replica:

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

Delivered (5 changesets):

• Task scheduler: FOR UPDATE SKIP LOCKED atomic claim replaces ListDue. CreateRunExclusive conditional insert for belt-and-suspenders uniqueness. Startup jitter (0–15s).
• WebSocket cross-pod delivery: PublishToUser routes through bus → pg_broadcast → remote pod. 18 SendToUser call sites migrated. tool.result.* routing changed to DirBoth for cross-pod WaitFor. TargetUserID field on Event.
• Shared ticket store: ws_tickets PG table with 30s TTL, atomic DELETE ... RETURNING validation. Replaces sync.Map.
• Shared rate limiter: rate_limit_counters PG table with fixed-window counters. Fail-open policy on DB errors.
• Health probes: /healthz/ready (PG ping, 2s timeout), /healthz/live (process alive). Helm: replicaCount: 2, pod anti-affinity, readiness/liveness probes.

Schema: 020_ha.sql — ws_tickets, rate_limit_counters.

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)
• Swagger/OpenAPI: auto-generated spec from route definitions, served at /api/docs

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)

v0.35.0 — Workflow Product

Bridge from workflow infrastructure to real business process automation. Visitors see forms (not just chat), collected data flows through Starlark enrichment, stages branch conditionally, and team members review structured data — not chat transcripts.

Depends on: v0.31.2 (team workflow self-service), v0.29.0 (Starlark sandbox).

Form Rendering Surface:

• Visitor form renderer — reads form_template from stage, renders HTML inputs (text, email, select, date, textarea, checkbox, file), validates client-side, submits via /w/:id/form-submit
• Progressive form — multi-step within a single stage (fieldsets)
• Conditional fields — show/hide based on previous answers
• File upload in forms — attach to stage_data via storage API
• Branded form page — uses workflow branding (colors, logo, tagline)

Data Pipeline (between-stage processing):

• on_advance hook — Starlark entry point fires after each stage transition, receives stage_data, can enrich/transform/reject
• External data enrichment — Starlark http.fetch pulls from external APIs, merges results into stage_data (reduce double entry)
• Data validation rules — Starlark on_validate can enforce cross-field business rules beyond per-field type checks
• Stage data schema — typed stage_data with declared fields, not opaque JSON blob. Enables structured review views

Conditional Routing:

• Branch expressions — transition_rules.condition evaluated against stage_data to select next stage (not always ordinal+1)
• AI-triggered routing — persona calls workflow_route tool with a target stage name based on conversation analysis
• Escalation pattern — "if AI confidence < threshold, route to human review stage" (help desk use case)
• Loop stages — return to a previous stage for correction without using reject (iterative data gathering)

Structured Review:

• Assignment review view — team member sees stage_data as a structured card/form, not just chat history
• Approval/reject with comments — reviewer adds notes visible to the next stage (not buried in chat)
• Side-by-side view — chat history + structured data together
• Bulk review — multiple assignments in a queue with keyboard nav

Monitoring Dashboard:

• Active instances list — workflow name, current stage, assignee, age, last activity
• Stage funnel — how many instances at each stage, bottleneck detection
• SLA timers — configurable per-stage, visible in review + dashboard
• Stale instance alerts — notify team admins when instances age out

Use case validation targets:

• Help desk: AI + KB → escalation to human → resolution tracking
• Data intake: form → Starlark enrichment → human review → follow-up
• Onboarding: multi-stage form → conditional branching → team assignment

---

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.2 (full package ecosystem, visual workflow builder, SDK-based surfaces, team workflow self-service)
• Operations track through v0.34.0 (multi-replica HA, observability, data portability)
• Workflow product v0.35.0 (form rendering, data pipeline, conditional routing, structured review, monitoring dashboard)

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)