From 92a33eff8a330685c9f6a9358c20051f5eead829 Mon Sep 17 00:00:00 2001 From: Xuepoo Date: Mon, 5 Oct 2026 04:59:17 +0800 Subject: [PATCH] [CTX-0078] docs(hygiene): remove research citations, add reference spine section, date evidence Closes #105. Manifest authority: drop research-repo citations, keep decision text under the accepted status. Lua-surface RFC: drop bitty-docs FIND and external CarryCtx identifiers, mark evidence revisions as drafting-time. sdk/reference: add Compatibility and versioning to all 12 reference pages per the reference spine. --- sdk/plugin-api-v1-lua-surface-rfc.md | 14 +++++++------- sdk/reference/commands.md | 10 ++++++++++ sdk/reference/env.md | 10 ++++++++++ sdk/reference/events.md | 10 ++++++++++ sdk/reference/keymaps.md | 10 ++++++++++ sdk/reference/notify.md | 10 ++++++++++ sdk/reference/process.md | 10 ++++++++++ sdk/reference/services.md | 10 ++++++++++ sdk/reference/settings.md | 10 ++++++++++ sdk/reference/store.md | 10 ++++++++++ sdk/reference/tasks-timers.md | 10 ++++++++++ sdk/reference/terminal.md | 10 ++++++++++ sdk/reference/ui.md | 10 ++++++++++ specifications/manifest-capability-authority.md | 5 +---- 14 files changed, 128 insertions(+), 11 deletions(-) diff --git a/sdk/plugin-api-v1-lua-surface-rfc.md b/sdk/plugin-api-v1-lua-surface-rfc.md index ea0928a..16b70cf 100644 --- a/sdk/plugin-api-v1-lua-surface-rfc.md +++ b/sdk/plugin-api-v1-lua-surface-rfc.md @@ -28,11 +28,13 @@ candidate spellings recorded in the corpus: | Candidate | Recorded in | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `bitty.commands.*`, `bitty.events.*`, `bitty.ui.*` namespaces | [Plugin Platform RFC host namespaces](../specifications/plugin-platform-rfc.md) (explicitly illustrative) | -| `bitty.api.register_panel/on_event/get_terminal_state` | `bitty-docs` finding `FIND-0003` `ECO-SDK-01` (recorded in the shared checkout; not yet on `origin/main`) | -| `register_panel/on_event/get_terminal_state` (R-SDK-1 gate list) | `bitty` CarryCtx note `PX-1199` (CTX-0221 first-plugin-batch plan, planning only) | +| `bitty.api.register_panel/on_event/get_terminal_state` | Draft-review note only; no accepted contract behind this spelling | +| `register_panel/on_event/get_terminal_state` (R-SDK-1 gate list) | First-plugin-batch plan (planning only; no accepted contract) | | `bitty.services:get(...)` colon-style methods | [Plugin Reuse and Provider Ecology RFC](../packaging/plugin-reuse-and-providers.md) (Draft, post-1.0 provider follow-up) | -Evidence revisions inspected read-only during drafting: `bitty` `1ea2f66` +Evidence revisions below are drafting-time evidence inspected read-only +before the 2026-09-11 ratification, not live verification pointers: +`bitty` `1ea2f66` (local checkout; `bitty-plugin-host` and `bitty-lua` sources; the workspace was behind `origin/main` at inspection time), `bitty-plugin-sdk` main at `0fbefe7` (manifest/lint, mock host, and conformance merged via CTX-0032/#57, @@ -652,11 +654,9 @@ dispositions are: [ADR 0006](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0006-os-env-policy.md), [ADR 0007](https://github.com/bitty-terminal/bitty-docs/blob/main/docs/decisions/adrs/ADR-0007-async-gc.md) — accepted runtime, environment, and async contracts. -- `FIND-0003` `ECO-SDK-01` (bitty-docs finding recorded in the shared - checkout; not yet committed to `origin/main` at draft time) — candidate - spelling and SDK readiness gap. - `bitty` `1ea2f66` — `crates/bitty-plugin-host/src/event.rs` (closed `EventKind`/`EventPayload`), `registry.rs`, `host.rs`, `capability.rs`, `manifest.rs`; `crates/bitty-lua/src/lib.rs` (VM budgets, no host bridge). -- `bitty-plugin-sdk` `0fbefe7` (main) — manifest/lint, mock host, and +- `bitty-plugin-sdk` `0fbefe7` (main at draft time; drafting-time evidence, + not a live verification pointer) — manifest/lint, mock host, and conformance; merged CTX-0032/#57, CTX-0033/#58, CTX-0036/#60, evidence only. diff --git a/sdk/reference/commands.md b/sdk/reference/commands.md index da4ec35..60d5c14 100644 --- a/sdk/reference/commands.md +++ b/sdk/reference/commands.md @@ -133,6 +133,16 @@ would be illustrative, never verified. form and the activation registration is checked after canonicalization; mismatch fails activation with a `validation` diagnostic (RFC, LUA-OQ-3). +## Compatibility and versioning + +Draft reference: this page states the candidate v1 spellings and carries no +compatibility promise while its status is draft. The target contract is the +[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy) +in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within +`1.x`, additions ship as minor versions, and removals or narrowings require a +major version, gated by the manifest `compat.plugin-api` range against the +runtime `bitty.api_version`. + ## References - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md) diff --git a/sdk/reference/env.md b/sdk/reference/env.md index 044fcd0..966dec0 100644 --- a/sdk/reference/env.md +++ b/sdk/reference/env.md @@ -164,6 +164,16 @@ granted-path claim beyond this denial shape is follow-up work. - Out of scope (no source): enumeration of keys, writes to the host environment, and any delivery, caching, or reload semantics. +## Compatibility and versioning + +Draft reference: this page states the candidate v1 spellings and carries no +compatibility promise while its status is draft. The target contract is the +[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy) +in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within +`1.x`, additions ship as minor versions, and removals or narrowings require a +major version, gated by the manifest `compat.plugin-api` range against the +runtime `bitty.api_version`. + ## References - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md) diff --git a/sdk/reference/events.md b/sdk/reference/events.md index 75d6dcb..0f5f523 100644 --- a/sdk/reference/events.md +++ b/sdk/reference/events.md @@ -143,6 +143,16 @@ end) payload-less kinds (whose v1 shape declares no fields), which reject any key (RFC compatibility policy). +## Compatibility and versioning + +Draft reference: this page states the candidate v1 spellings and carries no +compatibility promise while its status is draft. The target contract is the +[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy) +in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within +`1.x`, additions ship as minor versions, and removals or narrowings require a +major version, gated by the manifest `compat.plugin-api` range against the +runtime `bitty.api_version`. + ## References - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md) diff --git a/sdk/reference/keymaps.md b/sdk/reference/keymaps.md index 3b035a7..e58c953 100644 --- a/sdk/reference/keymaps.md +++ b/sdk/reference/keymaps.md @@ -121,6 +121,16 @@ chord)` (RFC). - Suggestions are generation-scoped captures owned by `(PluginId, generation)` and disposed with it. +## Compatibility and versioning + +Draft reference: this page states the candidate v1 spellings and carries no +compatibility promise while its status is draft. The target contract is the +[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy) +in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within +`1.x`, additions ship as minor versions, and removals or narrowings require a +major version, gated by the manifest `compat.plugin-api` range against the +runtime `bitty.api_version`. + ## References - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md) diff --git a/sdk/reference/notify.md b/sdk/reference/notify.md index 406f2ce..fc0e210 100644 --- a/sdk/reference/notify.md +++ b/sdk/reference/notify.md @@ -113,6 +113,16 @@ end - Granted-path delivery is pinned only by the `FakeServices` seam, not by a passing test; any delivery claim beyond acceptance is follow-up work. +## Compatibility and versioning + +Draft reference: this page states the candidate v1 spellings and carries no +compatibility promise while its status is draft. The target contract is the +[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy) +in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within +`1.x`, additions ship as minor versions, and removals or narrowings require a +major version, gated by the manifest `compat.plugin-api` range against the +runtime `bitty.api_version`. + ## References - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md) diff --git a/sdk/reference/process.md b/sdk/reference/process.md index 51bede6..73557e9 100644 --- a/sdk/reference/process.md +++ b/sdk/reference/process.md @@ -115,6 +115,16 @@ a wired host backend. directory, environment inheritance, streaming, signaling, and any normative v1 guarantee. +## Compatibility and versioning + +Draft reference: this page states the candidate v1 spellings and carries no +compatibility promise while its status is draft. The target contract is the +[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy) +in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within +`1.x`, additions ship as minor versions, and removals or narrowings require a +major version, gated by the manifest `compat.plugin-api` range against the +runtime `bitty.api_version`. + ## References - [Lua Reference Overview](overview.md) (error contract, capability gating, diff --git a/sdk/reference/services.md b/sdk/reference/services.md index 3cf17e2..e0ca15d 100644 --- a/sdk/reference/services.md +++ b/sdk/reference/services.md @@ -123,6 +123,16 @@ test exercises a wired backend. - Out of scope (no source): resolution ordering, caching, retry, timeouts, and any concrete interface names or schemas. +## Compatibility and versioning + +Draft reference: this page states the candidate v1 spellings and carries no +compatibility promise while its status is draft. The target contract is the +[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy) +in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within +`1.x`, additions ship as minor versions, and removals or narrowings require a +major version, gated by the manifest `compat.plugin-api` range against the +runtime `bitty.api_version`. + ## References - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md) diff --git a/sdk/reference/settings.md b/sdk/reference/settings.md index 6429969..25d1018 100644 --- a/sdk/reference/settings.md +++ b/sdk/reference/settings.md @@ -102,6 +102,16 @@ bitty.store.set("flag", retention) - Settings access never leaves the plugin's own namespace; cross-plugin or core settings reads are outside v1 (RFC). +## Compatibility and versioning + +Draft reference: this page states the candidate v1 spellings and carries no +compatibility promise while its status is draft. The target contract is the +[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy) +in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within +`1.x`, additions ship as minor versions, and removals or narrowings require a +major version, gated by the manifest `compat.plugin-api` range against the +runtime `bitty.api_version`. + ## References - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md) diff --git a/sdk/reference/store.md b/sdk/reference/store.md index 013914b..7ea197b 100644 --- a/sdk/reference/store.md +++ b/sdk/reference/store.md @@ -166,6 +166,16 @@ Further limits: module performs no I/O, and durability reduces to the host keeping the owning `PluginStore` alive across generations (`store.rs`). +## Compatibility and versioning + +Draft reference: this page states the candidate v1 spellings and carries no +compatibility promise while its status is draft. The target contract is the +[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy) +in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within +`1.x`, additions ship as minor versions, and removals or narrowings require a +major version, gated by the manifest `compat.plugin-api` range against the +runtime `bitty.api_version`. + ## References - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md) diff --git a/sdk/reference/tasks-timers.md b/sdk/reference/tasks-timers.md index cc8081e..d9c0614 100644 --- a/sdk/reference/tasks-timers.md +++ b/sdk/reference/tasks-timers.md @@ -145,6 +145,16 @@ Over-cap and handle-exhaustion behavior for both families is pinned by - Timer fire and task resumption deliver through the accepted event path, so the three-level queue budgets still apply (RFC). +## Compatibility and versioning + +Draft reference: this page states the candidate v1 spellings and carries no +compatibility promise while its status is draft. The target contract is the +[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy) +in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within +`1.x`, additions ship as minor versions, and removals or narrowings require a +major version, gated by the manifest `compat.plugin-api` range against the +runtime `bitty.api_version`. + ## References - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md) diff --git a/sdk/reference/terminal.md b/sdk/reference/terminal.md index 4728f85..b346916 100644 --- a/sdk/reference/terminal.md +++ b/sdk/reference/terminal.md @@ -122,6 +122,16 @@ local snap = bitty.terminal.snapshot({ scope = "semantic" }) rest on the `FakeServices` seam and the RFC shape, never on verified delivery. +## Compatibility and versioning + +Draft reference: this page states the candidate v1 spellings and carries no +compatibility promise while its status is draft. The target contract is the +[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy) +in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within +`1.x`, additions ship as minor versions, and removals or narrowings require a +major version, gated by the manifest `compat.plugin-api` range against the +runtime `bitty.api_version`. + ## References - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md) diff --git a/sdk/reference/ui.md b/sdk/reference/ui.md index 3ca1463..32353c2 100644 --- a/sdk/reference/ui.md +++ b/sdk/reference/ui.md @@ -223,6 +223,16 @@ UI slots require a matching claim declaration` - Out of scope (no source): focus behavior, panel routing, and any composer behavior beyond the internal scene-diff step. +## Compatibility and versioning + +Draft reference: this page states the candidate v1 spellings and carries no +compatibility promise while its status is draft. The target contract is the +[Compatibility policy](../plugin-api-v1-lua-surface-rfc.md#compatibility-policy) +in the accepted Plugin API v1 Lua Surface RFC: the surface is stable within +`1.x`, additions ship as minor versions, and removals or narrowings require a +major version, gated by the manifest `compat.plugin-api` range against the +runtime `bitty.api_version`. + ## References - [Plugin API v1 Lua Surface RFC](../plugin-api-v1-lua-surface-rfc.md) diff --git a/specifications/manifest-capability-authority.md b/specifications/manifest-capability-authority.md index ba95a4d..f99f1fb 100644 --- a/specifications/manifest-capability-authority.md +++ b/specifications/manifest-capability-authority.md @@ -33,8 +33,7 @@ sidebar_order: 19 ## Purpose and scope -The 2026-09-24 cross-contract review campaign -(`research/review/2026-09-24/11-final-cross-contracts.md`) identified five +Cross-contract review identified five grammar conflicts where SDK, host implementation, template, and canonical documentation disagreed: @@ -501,7 +500,5 @@ following criteria are satisfied: capability model. - [Package Follow-up RFC](../packaging/package-followup-rfc.md): resolver constraint grammar and prerelease policy. -- Cross-contract review campaign: - `research/review/2026-09-24/11-final-cross-contracts.md`, cluster CC-01. - Issues: bitty-plugins-docs #95 (parent contract decision), #96 (grammar publication).