Jeffrey Smith
23dddae0c5
Promote team roles to a kernel primitive with many-to-many support. Users can now hold multiple roles within a team simultaneously. - Migration 016: team_user_roles table (both dialects) - 6 new TeamStore methods (AddUserRole, RemoveUserRole, ListUserRoles, GetMemberRoles, HasRole, RemoveAllUserRoles) - RequireRole() middleware with OR semantics and system admin bypass - 3 new handler endpoints for member role CRUD - Manifest requires_roles field (advisory for v0.9.3) - Starlark teams module: get_member_roles(), has_role() - Team-admin UI: role badge chips + assignment dropdown - Fixed pre-existing SDK auto-unwrap bug in loadRoles - 10 new tests Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
12 KiB
Armature — Roadmap
Current: v0.9.x — Workflow Redesign + Multi-Surface Packages
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 (completed)
Many-to-many team_user_roles table. RequireRole() middleware.
Manifest requires_roles field (advisory). Starlark teams module
with get_member_roles() and has_role(). Team-admin UI with role
badge chips and assignment dropdown. 10 new tests.
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 — Panels + Composable Layout
Panels are a new kernel rendering tier between surfaces (full-page) and
block renderers (inline). They solve composable companion views — e.g.,
a notes reference panel inside chat. Design doc: docs/DESIGN-panels.md.
| Version | Title |
|---|---|
| v0.10.0 | Panel Manifest + Lifecycle |
| v0.10.1 | FloatingPanel Primitive |
| v0.10.2 | Docked Panels + Mode Transitions |
| v0.10.3 | Panel Communication Patterns |
| v0.10.4 | Reference Panel: Notes (basic) |
v0.11.x — Notes Reference Extension
Notes becomes the first reference extension — a production-quality
knowledge base that exercises every kernel primitive. The UI/UX redesign
is front-loaded as v0.11.0 so every subsequent feature version builds on
a clean visual foundation. Design doc: docs/DESIGN-notes-v011x.md.
| Version | Title |
|---|---|
| v0.11.0 | UI/UX Foundation — visual redesign |
| v0.11.1 | Deep Folders + Navigation |
| v0.11.2 | Wikilinks + Backlinks |
| v0.11.3 | Live Preview + Rich Editing |
| v0.11.4 | Note Sharing + Permissions |
| v0.11.5 | Graph + Outline Hardening |
| v0.11.6 | Quick Switcher + Commands |
| v0.11.7 | Daily Notes + Templates |
| v0.11.8 | Transclusion + Embeds |
| v0.11.9 | Composability: Slots + Actions |
| v0.11.10 | Panel Enhancement + Quality Gate |
v0.12.x — Reference Extensions (Remaining)
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.
| Version | Title |
|---|---|
| v0.12.0 | vector-store Library |
| v0.12.1 | llm-bridge Library |
| v0.12.2 | file-share Extension |
| v0.12.3 | code-workspace Extension |
| v0.12.4 | image-gen + image-edit Extensions |
| v0.12.5 | Chat System |
v0.13.x — Sidecar Tier + Polish
| Version | Title |
|---|---|
| v0.13.0 | Sidecar Tier |
| v0.13.1 | Native Dialog Audit |
| v0.13.2 | Stability + Migration Tooling |
v1.0.0 — Stable Release
Kernel API surface frozen. Extensions are the product.
Gate criteria:
- All kernel Starlark modules documented with examples
- All
api_routescovered 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
- Notes reference extension shipped with all v0.11.x features
- Notes UI/UX reviewed against v0.11.0 design principles — no placeholder UI
- At least 1 panel shipped and consumed cross-package (notes.reference → chat)
- Panel lifecycle test coverage in SDK test runner
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.13.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. |
| Panels as kernel primitive (v0.10.x) | Z-index coordination, drag/resize, layout negotiation are kernel concerns. |
| UI/UX redesign as v0.11.0 | Every feature version builds on the visual foundation. Front-loading avoids double work. |
| Notes as dedicated v0.11.x series (11 versions) | Complex enough to need changeset discipline. Each version independently shippable. |
| Notes before remaining reference extensions | Notes proves the full primitive surface. Other extensions build on proven patterns. |