From ce89d90700d8c134f56e92f87615375ce0f2e33f Mon Sep 17 00:00:00 2001 From: Xuepoo Date: Sun, 4 Oct 2026 19:07:58 +0800 Subject: [PATCH] docs(architecture): update overview diagram and first-party plugin inventory for Small-Core alignment Priority: P2 | Area: area:plugin | Labels: docs, P2, area:plugin | Milestone: v0.1.0 | Task: CTX-0076 Update architecture/diagrams/00-overview.mmd and recompile 00-overview.svg to reflect the Small-Core extraction boundaries: - First-party extracted policy plugins (bar/workspace per ADR-0014, composer per ADR-0015, search and copy-mode per W-138/Issue #1624, devtools) - Phodopus pure-Rust stackless Lua VM with fuel and memory bounds - Offline Extension Host and local staged store loading - Out-of-process bitty-plugin-manager CLI and DIR-017 Core network-free invariant - Register new L0 nodes in glossary.yaml and update README.md provenance - Synchronize docs/plugins/README.md with the first-party core policy plugins Closes #139 --- architecture/diagrams/00-overview.mmd | 35 ++++++++++++-- architecture/diagrams/00-overview.svg | 2 +- architecture/diagrams/README.md | 68 ++++++++++++++------------- architecture/diagrams/glossary.yaml | 53 ++++++++++++++++++++- docs/plugins/README.md | 14 +++++- 5 files changed, 131 insertions(+), 41 deletions(-) diff --git a/architecture/diagrams/00-overview.mmd b/architecture/diagrams/00-overview.mmd index b49240e..96a8c10 100644 --- a/architecture/diagrams/00-overview.mmd +++ b/architecture/diagrams/00-overview.mmd @@ -1,6 +1,31 @@ flowchart LR - PLUGIN["Plugin
one VM per ID plus generation
accepted: plugin-platform-rfc"] --> HOST["Extension Host
only executor, mediates privilege
accepted: plugin-platform-rfc"] - HOST -.->|"observation only
presentation, never truth"| TRUTH["Terminal Truth
core-owned grid and modes
accepted: plugin-system"] - REG["Registry
attestation and index only
accepted: package-followup-rfc"] --> HOST - SDK["SDK and Template
scaffold, lint, conformance
accepted: split-decision"] --> PLUGIN - PANEL(["Panel Boundary
container accepted, provider draft
ui-extensibility-arch"]) -.-> HOST + subgraph PLUGINS ["Plugin Ecosystem (Lua)"] + FP["First-Party Policy
bar, composer, search, copy-mode, devtools
accepted: ADR-0014, ADR-0015, W-138"] + TP["Third-Party Plugins
activity, file-manager, community
accepted: plugin-platform-rfc"] + end + + VM["Phodopus Lua VM
pure-Rust stackless VM, fuel & memory bounds
accepted: phodopus-runtime-candidate"] + + HOST["Extension Host
only executor, mediates privilege
accepted: plugin-platform-rfc"] + + MGR["Plugin Manager CLI
bitty-plugin-manager out-of-process
accepted: ADR-0015, DIR-017"] + REG["Registry
attestation and index only
accepted: package-followup-rfc"] + STORE["Local Staged Store
verified offline artifacts
accepted: host-runtime-rfc"] + + TRUTH["Terminal Truth
core PTY, grid buffers, raw modes
accepted: plugin-system"] + SURFACE(["UI Presentation & Insets
chrome insets, tabs, panels, overlays
accepted: ADR-0014, ui-extensibility-arch"]) + + SDK["SDK and Template
scaffold, lint, mock host conformance
accepted: split-decision"] + + REG -->|"out-of-process index & fetch
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
never mutates truth"| TRUTH + HOST -.->|"presentation & modal capture
chrome insets, tabs, overlays"| SURFACE diff --git a/architecture/diagrams/00-overview.svg b/architecture/diagrams/00-overview.svg index 15cdf47..d2984bb 100644 --- a/architecture/diagrams/00-overview.svg +++ b/architecture/diagrams/00-overview.svg @@ -1 +1 @@ -

observation only
presentation, never truth

Plugin
one VM per ID plus generation
accepted: plugin-platform-rfc

Extension Host
only executor, mediates privilege
accepted: plugin-platform-rfc

Terminal Truth
core-owned grid and modes
accepted: plugin-system

Registry
attestation and index only
accepted: package-followup-rfc

SDK and Template
scaffold, lint, conformance
accepted: split-decision

Panel Boundary
container accepted, provider draft
ui-extensibility-arch

\ No newline at end of file +

Plugin Ecosystem (Lua)

out-of-process index & fetch
DIR-017: Core network-free

stage verified packages

offline read

observation only
never mutates truth

presentation & modal capture
chrome insets, tabs, overlays

scaffold & lint

First-Party Policy
bar, composer, search, copy-mode, devtools
accepted: ADR-0014, ADR-0015, W-138

Third-Party Plugins
activity, file-manager, community
accepted: plugin-platform-rfc

Phodopus Lua VM
pure-Rust stackless VM, fuel & memory bounds
accepted: phodopus-runtime-candidate

Extension Host
only executor, mediates privilege
accepted: plugin-platform-rfc

Plugin Manager CLI
bitty-plugin-manager out-of-process
accepted: ADR-0015, DIR-017

Registry
attestation and index only
accepted: package-followup-rfc

Local Staged Store
verified offline artifacts
accepted: host-runtime-rfc

Terminal Truth
core PTY, grid buffers, raw modes
accepted: plugin-system

UI Presentation & Insets
chrome insets, tabs, panels, overlays
accepted: ADR-0014, ui-extensibility-arch

SDK and Template
scaffold, lint, mock host conformance
accepted: split-decision

\ No newline at end of file diff --git a/architecture/diagrams/README.md b/architecture/diagrams/README.md index d8d3f2a..420991a 100644 --- a/architecture/diagrams/README.md +++ b/architecture/diagrams/README.md @@ -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 diff --git a/architecture/diagrams/glossary.yaml b/architecture/diagrams/glossary.yaml index 5644be1..9bef32e 100644 --- a/architecture/diagrams/glossary.yaml +++ b/architecture/diagrams/glossary.yaml @@ -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) @@ -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" @@ -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 diff --git a/docs/plugins/README.md b/docs/plugins/README.md index 6486a5d..4a20500 100644 --- a/docs/plugins/README.md +++ b/docs/plugins/README.md @@ -35,6 +35,19 @@ contains them. | 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 | | `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 | | `bitty-terminal.bar` | Implemented, unified tab-bar and workspace insets | [bar](bar/README.md) | +| composer | | `bitty-terminal.composer` | Implemented Lua policy, overlay/submit/editor gate | [search-copy policy](../../specifications/search-copy-mode-policy.md) | +| search | | `bitty-terminal.search` | Candidate policy, bounded search over Core snapshots | [search-copy policy](../../specifications/search-copy-mode-policy.md) | +| copy-mode | | `bitty-terminal.copy-mode` | Candidate policy, keyboard selection over Core model | [search-copy policy](../../specifications/search-copy-mode-policy.md) | +| history | | `bitty-terminal.history` | Policy over local storage and shell integration | [history policy](../../extensibility/history-and-storage-policy.md) | +| 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 @@ -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. |