Jeffrey Smith
76c32be439
Some checks failed
CI/CD / detect-changes (pull_request) Successful in 3s
CI/CD / test-runners (pull_request) Has been skipped
CI/CD / e2e-smoke (pull_request) Has been skipped
CI/CD / test-frontend (pull_request) Successful in 4s
CI/CD / build-and-deploy (pull_request) Has been cancelled
CI/CD / test-sqlite (pull_request) Has been cancelled
CI/CD / test-go-pg (pull_request) Has been cancelled
Completed v0.6.x–v0.8.x sections collapsed to summary tables — detail lives in CHANGELOG.md. New v0.9.x series: workflow system redesign (converter consolidation, team roles, typed forms promotion, stage_mode collapse, full r/w Starlark module, multi-surface manifest). Old 0.9.x reference extensions shift to 0.10.x, sidecar tier to 0.11.x. New design doc: docs/DESIGN-workflow-redesign.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
275 lines
11 KiB
Markdown
275 lines
11 KiB
Markdown
# 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 — Workflow Redesign
|
|
|
|
Design doc: `docs/DESIGN-workflow-redesign.md`
|
|
|
|
The workflow system (~7,600 lines, 25+ files) was built incrementally and
|
|
has accumulated redundant concepts, buried primitives, and a read-only
|
|
Starlark module. This series cleans up the debt and promotes reusable
|
|
primitives before building reference extensions on top.
|
|
|
|
**v0.9.0 — Starlark Converter Consolidation + Snapshot Cleanup**
|
|
|
|
Three files contain near-identical Go↔Starlark converters; three copies
|
|
of the snapshot parser exist. Consolidate into `sandbox/convert.go` and
|
|
one exported snapshot function. Standardize on wrapped snapshot format.
|
|
|
|
**v0.9.1 — 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.2 — 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.3 — 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.4 — 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.
|
|
`review` was just `delegated` with signoff — signoff is independent of
|
|
rendering mode.
|
|
|
|
**v0.9.5 — 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. Unlocks fully automated workflow
|
|
orchestration from Starlark hooks and extensions.
|
|
|
|
**v0.9.6 — 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.7 — Multi-Surface Manifest + Route Resolution**
|
|
|
|
Packages can declare multiple surface routes with independent access
|
|
controls. Kernel resolves routes per-page. Enables mixed public/auth
|
|
pages in a single package.
|
|
|
|
**v0.9.8 — Surface Access via Roles**
|
|
|
|
Wire team roles (v0.9.1) 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. |
|