Skip to content

docs(architecture): update overview diagram and first-party plugin inventory for Small-Core alignment #140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Xuepoo merged 1 commit into from
Oct 4, 2026
Merged

docs(architecture): update overview diagram and first-party plugin inventory for Small-Core alignment #140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 30 additions & 5 deletions architecture/diagrams/00-overview.mmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,31 @@
flowchart LR
PLUGIN["Plugin<br/>one VM per ID plus generation<br/>accepted: plugin-platform-rfc"] --> HOST["Extension Host<br/>only executor, mediates privilege<br/>accepted: plugin-platform-rfc"]
HOST -.->|"observation only<br/>presentation, never truth"| TRUTH["Terminal Truth<br/>core-owned grid and modes<br/>accepted: plugin-system"]
REG["Registry<br/>attestation and index only<br/>accepted: package-followup-rfc"] --> HOST
SDK["SDK and Template<br/>scaffold, lint, conformance<br/>accepted: split-decision"] --> PLUGIN
PANEL(["Panel Boundary<br/>container accepted, provider draft<br/>ui-extensibility-arch"]) -.-> HOST
subgraph PLUGINS ["Plugin Ecosystem (Lua)"]
FP["First-Party Policy<br/>bar, composer, search, copy-mode, devtools<br/>accepted: ADR-0014, ADR-0015, W-138"]
TP["Third-Party Plugins<br/>activity, file-manager, community<br/>accepted: plugin-platform-rfc"]
end

VM["Phodopus Lua VM<br/>pure-Rust stackless VM, fuel & memory bounds<br/>accepted: phodopus-runtime-candidate"]

HOST["Extension Host<br/>only executor, mediates privilege<br/>accepted: plugin-platform-rfc"]

MGR["Plugin Manager CLI<br/>bitty-plugin-manager out-of-process<br/>accepted: ADR-0015, DIR-017"]
REG["Registry<br/>attestation and index only<br/>accepted: package-followup-rfc"]
STORE["Local Staged Store<br/>verified offline artifacts<br/>accepted: host-runtime-rfc"]

TRUTH["Terminal Truth<br/>core PTY, grid buffers, raw modes<br/>accepted: plugin-system"]
SURFACE(["UI Presentation & Insets<br/>chrome insets, tabs, panels, overlays<br/>accepted: ADR-0014, ui-extensibility-arch"])

SDK["SDK and Template<br/>scaffold, lint, mock host conformance<br/>accepted: split-decision"]

REG -->|"out-of-process index & fetch<br/>DIR-017: Core network-free"| MGR
MGR -->|"stage verified packages"| STORE
STORE -->|"offline read"| HOST

FP --> VM
TP --> VM
VM --> HOST

SDK -.->|"scaffold & lint"| PLUGINS

HOST -.->|"observation only<br/>never mutates truth"| TRUTH
HOST -.->|"presentation & modal capture<br/>chrome insets, tabs, overlays"| SURFACE
2 changes: 1 addition & 1 deletion architecture/diagrams/00-overview.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
68 changes: 36 additions & 32 deletions architecture/diagrams/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,38 +53,42 @@ accepts them.

## Node provenance

| Diagram | Node | Status | Traces to |
| -------------- | -------------------- | -------- | ----------------------------------------------------------------------- |
| `00-overview` | Plugin | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `00-overview` | Extension Host | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `00-overview` | Terminal Truth | accepted | [Plugin system](../../extensibility/plugin-system.md) |
| `00-overview` | Registry | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `00-overview` | SDK and Template | accepted | [Split Decision](../../product/bundled-plugin-split-decision.md) |
| `00-overview` | Panel Boundary | draft | [UI Extensibility](../../architecture/ui-extensibility-architecture.md) |
| `01-lifecycle` | bitty-plugin.toml | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `01-lifecycle` | Capability Grant | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `01-lifecycle` | Lua VM | accepted | [Lua Runtime RFC](../../runtime/lua-runtime-rfc.md) |
| `01-lifecycle` | Discovered..Retained | accepted | [Package Lifecycle RFC](../../packaging/package-lifecycle-rfc.md) |
| `01-lifecycle` | Integrity Chain | accepted | [Package Lifecycle RFC](../../packaging/package-lifecycle-rfc.md) |
| `01-lifecycle` | Publisher Trust | accepted | [Package Lifecycle RFC](../../packaging/package-lifecycle-rfc.md) |
| `01-lifecycle` | Declared..Disposed | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `01-lifecycle` | Generation | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `01-lifecycle` | Event Pipeline | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `01-lifecycle` | Plugin Store | accepted | [Host Runtime RFC](../../runtime/plugin-host-runtime-rfc.md) |
| `01-lifecycle` | bitty safe | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `02-registry` | Official Entry | accepted | [Onboarding](../../product/official-plugin-onboarding.md) |
| `02-registry` | Community Entry | accepted | [Onboarding](../../product/official-plugin-onboarding.md) |
| `02-registry` | Index Snapshot | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `02-registry` | Client Verify | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `02-registry` | Key Directory | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `02-registry` | Source Classes | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `02-registry` | Resolver | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `02-registry` | Lockfile | accepted | [Package Lifecycle RFC](../../packaging/package-lifecycle-rfc.md) |
| `02-registry` | Template..Mock Host | accepted | [Split Decision](../../product/bundled-plugin-split-decision.md) |
| `02-registry` | Panel Container | accepted | [Split Decision](../../product/bundled-plugin-split-decision.md) |
| `02-registry` | Panel Provider | draft | [UI Extensibility](../../architecture/ui-extensibility-architecture.md) |
| `02-registry` | Presentation Modes | draft | [Ecosystem Model](../../architecture/plugin-ecosystem-model.md) |
| `02-registry` | Declarative Slots | accepted | [API v1 Surface](../../sdk/plugin-api-v1-lua-surface-rfc.md) |
| Diagram | Node | Status | Traces to |
| -------------- | ------------------------ | -------- | ----------------------------------------------------------------------- |
| `00-overview` | First-Party Policy | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `00-overview` | Third-Party Plugins | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `00-overview` | Phodopus Lua VM | accepted | [Phodopus Runtime](../../runtime/phodopus-runtime-candidate.md) |
| `00-overview` | Extension Host | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `00-overview` | Plugin Manager CLI | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `00-overview` | Registry | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `00-overview` | Local Staged Store | accepted | [Host Runtime RFC](../../runtime/plugin-host-runtime-rfc.md) |
| `00-overview` | Terminal Truth | accepted | [Plugin system](../../extensibility/plugin-system.md) |
| `00-overview` | UI Presentation & Insets | accepted | [UI Extensibility](../../architecture/ui-extensibility-architecture.md) |
| `00-overview` | SDK and Template | accepted | [Split Decision](../../product/bundled-plugin-split-decision.md) |
| `01-lifecycle` | bitty-plugin.toml | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `01-lifecycle` | Capability Grant | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `01-lifecycle` | Lua VM | accepted | [Lua Runtime RFC](../../runtime/lua-runtime-rfc.md) |
| `01-lifecycle` | Discovered..Retained | accepted | [Package Lifecycle RFC](../../packaging/package-lifecycle-rfc.md) |
| `01-lifecycle` | Integrity Chain | accepted | [Package Lifecycle RFC](../../packaging/package-lifecycle-rfc.md) |
| `01-lifecycle` | Publisher Trust | accepted | [Package Lifecycle RFC](../../packaging/package-lifecycle-rfc.md) |
| `01-lifecycle` | Declared..Disposed | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `01-lifecycle` | Generation | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `01-lifecycle` | Event Pipeline | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `01-lifecycle` | Plugin Store | accepted | [Host Runtime RFC](../../runtime/plugin-host-runtime-rfc.md) |
| `01-lifecycle` | bitty safe | accepted | [Plugin Platform RFC](../../specifications/plugin-platform-rfc.md) |
| `02-registry` | Official Entry | accepted | [Onboarding](../../product/official-plugin-onboarding.md) |
| `02-registry` | Community Entry | accepted | [Onboarding](../../product/official-plugin-onboarding.md) |
| `02-registry` | Index Snapshot | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `02-registry` | Client Verify | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `02-registry` | Key Directory | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `02-registry` | Source Classes | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `02-registry` | Resolver | accepted | [Package Follow-up RFC](../../packaging/package-followup-rfc.md) |
| `02-registry` | Lockfile | accepted | [Package Lifecycle RFC](../../packaging/package-lifecycle-rfc.md) |
| `02-registry` | Template..Mock Host | accepted | [Split Decision](../../product/bundled-plugin-split-decision.md) |
| `02-registry` | Panel Container | accepted | [Split Decision](../../product/bundled-plugin-split-decision.md) |
| `02-registry` | Panel Provider | draft | [UI Extensibility](../../architecture/ui-extensibility-architecture.md) |
| `02-registry` | Presentation Modes | draft | [Ecosystem Model](../../architecture/plugin-ecosystem-model.md) |
| `02-registry` | Declarative Slots | accepted | [API v1 Surface](../../sdk/plugin-api-v1-lua-surface-rfc.md) |

Provider-ecology nodes (`Service Registry`, `Provider Ecology`, `Lua Is
Glue`, `Self-Contained Artifact`) live in the glossary as draft
Expand Down
53 changes: 51 additions & 2 deletions architecture/diagrams/glossary.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@
# Visual rules: rect=module/store, rounded=capability/state, dashed=boundary/unaccepted, solid=call/depends, dashed-edge=event/async
# Levels: L0 overview, L1 subsystem, L2 flow
schema_version: 1
updated: "2026-09-19"
provenance: CTX-0032
updated: "2026-10-04"
provenance: CTX-0076
description: Canonical node and edge inventory for plugin-side architecture diagrams
sources:
- specifications/plugin-contract-direction.md (draft, candidate direction)
Expand All @@ -25,6 +25,7 @@ sources:
- product/official-plugin-onboarding.md (normative policy)
- extensibility/plugin-system.md (draft, accepted direction where marked)
- extensibility/package-management.md (draft, candidate contracts)
- runtime/phodopus-runtime-candidate.md (candidate, pure-Rust Lua VM)

visual_rules:
rect: "module / store — Mermaid rectangle"
Expand All @@ -41,6 +42,54 @@ levels:

nodes:
# --- L0 overview (plugin-side context) ---
- id: first-party-policy
label: First-Party Policy
kind: capability
shape: rect
level: L0
status: accepted
description: Official first-party policy plugins extracted from Core (bar/tabs, composer, search, copy-mode, devtools)
source: specifications/plugin-platform-rfc.md
- id: third-party-plugins
label: Third-Party Plugins
kind: capability
shape: rect
level: L0
status: accepted
description: Community and featured plugin instances executed under untrusted-by-default posture
source: specifications/plugin-platform-rfc.md
- id: phodopus-vm
label: Phodopus Lua VM
kind: module
shape: rect
level: L0
status: accepted
description: Pure-Rust stackless Lua VM with fuel metering, memory bounds, and isolated state per plugin and generation
source: runtime/phodopus-runtime-candidate.md
- id: plugin-manager
label: Plugin Manager CLI
kind: module
shape: rect
level: L0
status: accepted
description: Out-of-process bitty-plugin-manager CLI resolving, verifying, and staging packages outside Core (DIR-017)
source: packaging/package-followup-rfc.md
- id: local-store
label: Local Staged Store
kind: store
shape: rect
level: L0
status: accepted
description: Local verified plugin store loaded offline by Extension Host without network initiation
source: runtime/plugin-host-runtime-rfc.md
- id: ui-presentation
label: UI Presentation & Insets
kind: domain
shape: rounded
level: L0
status: accepted
description: Chrome insets, tab presentations, panels, and modal overlays hosted by plugins over generic slots (ADR-0014)
source: architecture/ui-extensibility-architecture.md
- id: plugin
label: Plugin
kind: capability
Expand Down
14 changes: 13 additions & 1 deletion docs/plugins/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,19 @@ contains them.
| file-manager | <https://github.com/bitty-terminal/file-manager> | `bitty-terminal.file-manager` | Independent package implemented headlessly, panel presentation deferred pending the panel-provider contract; registry entry published | [file-manager](file-manager/README.md) |
| git-panel | <https://github.com/bitty-terminal/git-panel> | `bitty-terminal.git-panel` | Independent package implemented headlessly, panel presentation deferred pending the panel-provider contract; registry entry published | [git-panel](git-panel/README.md) |

## First-party core policy plugins

Extracted from terminal core under Small-Core architectural boundaries (ADR-0014, ADR-0015, W-138):

| Plugin | Repository | Plugin id | Stage | Documentation |
| --------- | --------------------------------------------- | -------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------- |
| bar | <https://github.com/bitty-terminal/bar> | `bitty-terminal.bar` | Implemented, unified tab-bar and workspace insets | [bar](bar/README.md) |
| composer | <https://github.com/bitty-terminal/composer> | `bitty-terminal.composer` | Implemented Lua policy, overlay/submit/editor gate | [search-copy policy](../../specifications/search-copy-mode-policy.md) |
| search | <https://github.com/bitty-terminal/search> | `bitty-terminal.search` | Candidate policy, bounded search over Core snapshots | [search-copy policy](../../specifications/search-copy-mode-policy.md) |
| copy-mode | <https://github.com/bitty-terminal/copy-mode> | `bitty-terminal.copy-mode` | Candidate policy, keyboard selection over Core model | [search-copy policy](../../specifications/search-copy-mode-policy.md) |
| history | <https://github.com/bitty-terminal/history> | `bitty-terminal.history` | Policy over local storage and shell integration | [history policy](../../extensibility/history-and-storage-policy.md) |
| devtools | <https://github.com/bitty-terminal/devtools> | `bitty-featured.devtools` | Read-only runtime inspection and event tracing | [diagrams](../../architecture/diagrams/README.md) |

## Candidate plugins

The list below records documentation candidates from draft planning. None of
Expand All @@ -45,7 +58,6 @@ contract is accepted.

| Plugin | Batch | Documentation status | Planning notes |
| ------------- | ----- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| bar | First | Candidate page set ([bar](bar/README.md)) | Waybar-style unified 1-row bar consolidating workspace tabs and statusline. |
| beacon | TBD | Candidate page set ([beacon](beacon/README.md)) | Official Lua policy plugin for the accepted Core `TargetEngine` and `AnnotationEngine` mechanism; no package or repository exists yet. |
| scratchpad | First | Not started | Ephemeral per-directory notes. |
| peek | First | Not started | Hover and preview anchored to semantic zones or rich blocks. |
Expand Down
Loading