core/ROADMAP.md

# Armature — Roadmap

## Current: v0.9.x — Workflow Redesign

Self-hosted extensible platform kernel. Auth, identity, packages, Starlark
sandbox, storage, realtime, and ops are kernel primitives. Everything else
is an extension.

**Kernel capabilities:** Auth (builtin/mTLS/OIDC) · Users/teams/groups/RBAC ·
Surfaces/extensions/libraries/workflows · Starlark sandbox (capability-gated) ·
Object storage (PVC/S3) + ext_data tables · WebSocket hub + realtime pub/sub ·
Audit log · Notifications · Scheduled tasks · Cluster registry + HA ·
Extension composability (slots/contributes/cross-package calls)

---

## Completed — v0.6.x through v0.8.x

All completed work is documented in `CHANGELOG.md`.

### v0.6.x — MVP + Hardening

| Version | Title |
|---------|-------|
| v0.6.0 | Cluster Registry + HA |
| v0.6.1 | Backup/Restore + Docs |
| v0.6.2 | Docs Polish + Dynamic OpenAPI |
| v0.6.3 | Dead Code Sweep + Registry Fix |
| v0.6.4 | Admin Health/Metrics + Cluster Merge |
| v0.6.5 | Renderer Pipeline + Docs Rewrite |
| v0.6.6 | Final Hardening |
| v0.6.7 | Native mTLS |
| v0.6.8 | Rebrand + Cookie Fix |
| v0.6.9 | Session Lifetime Config |
| v0.6.10 | Viewport Foundation |
| v0.6.11 | CSS Deduplication |
| v0.6.12 | Extension CSS Isolation |
| v0.6.13 | Responsive & Spacing |
| v0.6.14 | Visual Polish |
| v0.6.15 | User Display Audit |
| v0.6.16 | Usability Survey Gate |
| v0.6.17 | Bug Fixes & Welcome |
| v0.6.18 | CI Bundle Wiring |

### v0.7.x — Test Infrastructure + Quality Gate

| Version | Title |
|---------|-------|
| v0.7.0 | Shell Contract + Surface Audit + Rebrand |
| v0.7.1 | Surface Runner Framework |
| v0.7.2 | Package Runners + CI Gate |
| v0.7.3 | Extension Shell Migration |
| v0.7.4 | Documentation + Surface Work |
| v0.7.5 | Headless E2E + CI Gate |
| v0.7.6 | Code Hygiene + Test Coverage |
| v0.7.7 | API Tokens + Extension Permissions |
| v0.7.8 | Bug Fixes & Admin Gaps |
| v0.7.9 | Workflow Independence Audit |
| v0.7.10 | Workflow Handoff + Assignment UI |
| v0.7.11 | Query & HTTP Ergonomics |
| v0.7.12 | Concurrent Execution Primitive |

### v0.8.x — Storage Primitives + Composability (Kernel Complete)

| Version | Title |
|---------|-------|
| v0.8.0 | `files` Module |
| v0.8.1 | `workspace` Module |
| v0.8.2 | Capability Negotiation |
| v0.8.3 | Vector Column Type |
| v0.8.4 | Documentation Refresh + Surface Sizing Fix |
| v0.8.5 | Extension Composability |

---

## Planned

### v0.9.x — Multi-Surface Packages + Workflow Redesign

**v0.9.0 — Multi-Surface Packages** *(completed)*

Packages declare a `surfaces` array with per-path access controls,
titles, and layouts. Unified route tree dispatches between surface
rendering and ext API calls. `sw.navigate()` for client-side sub-path
routing. Design doc: `docs/DESIGN-multi-surface.md`.

**v0.9.1 — Server-Side Sub-Path Routing** *(completed)*

Consolidated root and catch-all route handlers into a unified dispatcher.
Added `aggregateAccess()` for early auth short-circuit on all-authenticated
packages. SDK seeds initial history state for back-button resilience.
8 handler integration tests + 5 aggregateAccess unit tests.

**v0.9.2 — Starlark Converter Consolidation + Snapshot Cleanup** *(completed)*

Consolidated duplicate Go↔Starlark converters into `sandbox/convert.go`
(4 exported functions) and snapshot parsers into `models/snapshot.go`.
Standardized on wrapped snapshot format. ~350 lines of duplication removed.
Design doc: `docs/DESIGN-workflow-redesign.md`.

**v0.9.3 — Team User Roles**

Promote the buried role system to a kernel primitive. New
`team_user_roles` table (many-to-many). Manifest `requires_roles` field.
Team admin UI for role assignment. Kernel middleware `RequireRole()`.
Starlark SDK: `teams.get_member_roles()`, `teams.has_role()`.

**v0.9.4 — Package Adoption + Roles**

`scope: adoptable` manifest field. When a team adopts an adoptable
package, the package's `requires_roles` auto-populate into the team's
role slots. Replaces `AdoptTeamWorkflow` clone mechanism.

**v0.9.5 — Typed Forms → SDK Primitive**

Extract `TypedFormTemplate`, `FormField`, `FormFieldset`, etc. from
`models/workflow.go` into a `forms` package. FE SDK: `sw.forms.render()`
and `sw.forms.validate()`. Starlark: `forms.validate()`. Any package
can declare forms, not just workflow stages.

**v0.9.6 — Deprecate `stage_type`, Collapse `stage_mode`**

`stage_type` (simple/dynamic/automated) is redundant with `starlark_hook`
presence. Remove from new manifests, keep parsing for backward compat.
Collapse `stage_mode` from 4 to 3 values: form / delegated / automated.

**v0.9.7 — Full Read/Write Workflow Starlark Module**

Add `workflow.start()`, `workflow.advance()`, `workflow.cancel()`,
`workflow.submit_signoff()` to the Starlark module. Extract engine
interface to break circular import.

**v0.9.8 — Conditional Routing → SDK Primitive**

Expose `routing.evaluate(rules, data)` as a Starlark SDK function.
Branch rules become a reusable decision engine for any extension.

**v0.9.9 — Surface Access via Roles**

Wire team roles (v0.9.3) into surface access declarations:
`access: role:approver`. Kernel middleware checks role membership.
Completes the workflow→package access story.

---

### v0.10.x — Reference Extensions

The kernel is complete. This series proves the platform by shipping
first-party extensions that exercise every primitive. These are
**extensions, not kernel code** — they ship as `.pkg` files and can be
uninstalled.

**v0.10.0 — `vector-store` Library**

Document ingestion, chunk storage, embedding persistence, semantic
similarity search. Consumes: `db.write`, `files.read`.

**v0.10.1 — `llm-bridge` Library**

Model abstraction, tool-use routing, provider BYOK via connections.
Exposes `complete()`, `embed()`, `classify()`, `register_tool()`.
Consumes: `connections.read`, `api.http`, `db.write`.

**v0.10.2 — `file-share` Extension**

File upload, storage via `files` module, download links, team/group
ACLs via resource grants.

**v0.10.3 — `code-workspace` Extension**

Managed code repos via `workspace` module. Git operations, file browser
surface, structural indexing. Consumes: `workspace.manage`, `files.write`.

**v0.10.4 — `image-gen` + `image-edit` Extensions**

Image generation/editing via external APIs. Composability demo:
contributes to `chat:image-actions` slot.

**v0.10.5 — Chat System**

Generic 1-to-N messaging with slots. `chat-core` library + `chat`
surface. Declares `chat:message-actions`, `chat:image-actions`,
`chat:composer-tools` slots. Consumes: `db.write`, `realtime.publish`,
`files.write`.

---

### v0.11.x — Sidecar Tier + Polish

**v0.11.0 — Sidecar Tier**

Out-of-process extensions for workloads that can't run in Starlark (ML
inference, media transcoding, language servers, local git). Sidecars are
independent processes that connect inward to the kernel, following the
cluster registry pattern. Authentication via mTLS or registration tokens.

**v0.11.1 — Native Dialog Audit**

Replace `prompt()`/`confirm()`/`alert()` with `sw.dialog` SDK primitives.

**v0.11.2 — Stability + Migration Tooling**

Versioned migrations, `armature migrate` CLI, backup/restore validation,
pre-1.0 schema freeze.

---

### v1.0.0 — Stable Release

Kernel API surface frozen. Extensions are the product.

Gate criteria:

- All kernel Starlark modules documented with examples
- All `api_routes` covered by OpenAPI spec
- Upgrade path tested from v0.8.0 → v1.0.0
- At least 3 reference extensions shipped (vector-store, llm-bridge, chat)
- At least 1 cross-extension composability demo (image-gen → chat:image-actions)
- Headless E2E green on PG + SQLite
- `armature-ca.sh` + mTLS deployment guide
- Single-binary + Docker + K8s deployment paths documented

---

## Post-1.0 Horizon

These are candidates, not commitments. Each requires a design doc.

- **Federation** — cross-instance package sharing, identity federation
- **Package marketplace** — signing, review, discovery registry
- **Desktop app** — Tauri wrapper for local-first deployment
- **Offline/sync** — SQLite-first with PG sync for field deployments
- **Multi-tenant SaaS mode** — tenant isolation at the team boundary

---

## Design Principles

| Principle | Implication |
|-----------|-------------|
| Extensions are the product | Chat, tasks, LLM, vector search, file sharing — all extensions. Zero kernel awareness of domain logic. |
| Kernel stays thin | New kernel primitives require justification. If it can be an extension, it must be. |
| Progressive enhancement | Every feature works on SQLite. PG adds performance. pgvector adds native vectors. S3 adds scalable storage. |
| KISS-first | No unnecessary dependencies. Preact+htm (3KB), single binary, dual-DB from one codebase. |
| Changeset discipline | Each CS independently CI-green. Design docs as implementation contracts. |
| Pre-1.0 migration freedom | Schema changes fold into existing migrations. Post-1.0: proper versioned migrations. |

---

## Design Decisions Log

| Decision | Rationale |
|----------|-----------|
| Tasks → extension | Three trigger primitives replace the monolithic scheduler. |
| Sessions removed | Workflow instances with dedicated storage replace kernel sessions. |
| `custom` stage mode | Delegates to a surface package, proving extension composability. |
| Providers removed from kernel | Connections + Starlark `provider.complete` as the interface. |
| Kernel permissions simplified | 6 platform permissions. Extensions define their own. |
| Preact+htm retained | 3KB runtime, no build step, KISS. |
| Single Docker image | Go binary + assets + migrations. |
| Admin → RBAC group | Grant check replaces role check. |
| Settings cascade | Scope auth + `user_overridable`. Two orthogonal axes. |
| Chat as extension, not kernel | Zero kernel awareness. Proves extensibility thesis. |
| PG as consensus layer | UNLOGGED node_registry + LISTEN/NOTIFY. No etcd/Consul/Redis. |
| Two trigger tiers | Extension-declared (full sandbox) vs user ad-hoc (restricted). |
| Two-slot topbar model | Left slot (title/branding) + center slot (`flex: 1`, tabs/pickers). |
| `db` module is the structured store | No separate KV primitive. Extensions declare tables. |
| `files` module rides ObjectStore | No new kernel tables. Metadata as companion objects. |
| `workspace` for real filesystem | Flat blob store can't serve git/compilers/ffmpeg. Managed disk paths. |
| Capability negotiation at install | Fail loud with actionable message, not silently at runtime. |
| Vector column with three-tier fallback | Works everywhere, works fast with pgvector. |
| Sidecar deferred to v0.11.x | HTTP module covers external APIs. Sidecars connect inward (no k8s RBAC needed). |
| Workflow redesign before reference extensions | Clean up debt and promote primitives before building on top. |