Skip to content

Commit c6cec64

Browse files
wesbillmanCarl
andauthored
docs: make native development the acceptance path (#666)
Signed-off-by: Carl <32a2e2c9d428ee08902cab75d956da2c1d235a22d4766b0dd4138bf6e2e5db1d@buzz.block.builderlab.xyz> Co-authored-by: Carl <32a2e2c9d428ee08902cab75d956da2c1d235a22d4766b0dd4138bf6e2e5db1d@buzz.block.builderlab.xyz>
1 parent 11fa9f2 commit c6cec64

5 files changed

Lines changed: 87 additions & 30 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,11 @@ per-platform steps and limits.
7272

7373
## Relay channels
7474

75+
For manual testing of shipped behavior, use `BUZZ_DEV_VIEWER= just desktop` to
76+
exercise the native path, even if `.env.local` contains a public viewer pin.
77+
Broker-backed runs do not count as acceptance. New features do not get broker
78+
support; see [host boundaries and testing guidance](docs/contributing.md#shared-logic-and-host-boundaries).
79+
7580
Live **browser/broker development** requires an existing Buzz account in the OS credential
7681
store: the `buzz-desktop` / `secrets` Keychain entry on macOS, or the same entry in
7782
the freedesktop secret service on Linux (read with libsecret's `secret-tool`, so

‎dev/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,6 @@ for the runtime/identity matrix, ownership rules and cross-host test expectation
99
Keep platform-neutral feature policy under its existing `src/features/*` owner;
1010
retain host custody and boundary enforcement here. Existing tests are discovered
1111
by Vitest. [Broker setup](../README.md#relay-channels) requires an explicit public
12-
identity pin; never put a private key in environment configuration.
12+
identity pin; never put a private key in environment configuration. The broker is
13+
being shrunk and does not receive new feature support. Use the native path for
14+
manual acceptance; see the [broker reduction sequence](../docs/contributing.md#broker-reduction-sequence).

‎dev/channel-kit.test.mjs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,10 @@ it("expands multiple teams and individual agents by exact key without namesake c
142142
);
143143
});
144144

145+
it("keeps the shared Canvas signing corpus nonempty", () => {
146+
expect(canvasCases.length).toBeGreaterThan(0);
147+
});
148+
145149
// Shape only: the broker additionally checks freshness; Rust also deserializes
146150
// EventTemplate and bounds the signed serialization. See contributing.md.
147151
it.each(canvasCases)("Canvas signing shape: $name", ({ accepted, tags }) => {

‎docs/contributing.md‎

Lines changed: 71 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -199,16 +199,20 @@ notification settings.
199199
## Shared logic and host boundaries
200200

201201
Browser and desktop share the React application, community sessions, durable
202-
outbox, protocol models and live scheduler. `dev/` is the Node host for browser
203-
development and broker-backed tests, not generated output or another relay.
204-
Packaged desktop uses the Rust host. Node code does not run in a browser merely
205-
because it serves one, and packaged desktop does not need a Node backend.
202+
outbox, protocol models and live scheduler. **The goal is one code path per feature
203+
in development and release:** desktop development uses the same shared frontend
204+
and Rust host as packaged desktop, not a Node implementation of the feature.
205+
`dev/` is only for browser-only development and broker tests, and is being shrunk;
206+
it is not a second product backend. New features do not get broker support. A
207+
pinned `just web` run therefore cannot reach new native features; develop and test
208+
those with `BUZZ_DEV_VIEWER= just desktop` instead. Node code does not run in a
209+
browser merely because it serves one, and packaged desktop has no Node backend.
206210

207211
| Mode | Identity and relay host |
208212
| --- | --- |
209213
| `just web`, public `BUZZ_DEV_VIEWER` pin | Node broker using the pinned existing legacy identity (macOS/Linux) |
210214
| `just web`, no pin | Shell/fixtures; no live broker identity |
211-
| `just desktop`, public pin | Legacy broker identity/relay access, even inside the native window; native-only capabilities may coexist |
215+
| `just desktop`, public pin | Legacy broker identity/relay access inside the native window; native identity is disabled (not an acceptance mode) |
212216
| `just desktop`, no pin | Native identity/relay access on supported macOS, Windows and Linux |
213217
| Packaged desktop | Native host; production builds exclude the dev broker regardless of the pin |
214218

@@ -229,16 +233,22 @@ app as incidental cleanup. See [identity custody and acceptance](identity.md).
229233
[community commands](../src/features/communities/admin-protocol.ts) are examples.
230234
Shared modules must not depend on Node, Tauri or a dev-host implementation.
231235
- Keep signing keys, decryption, secure storage, subprocesses and host I/O in the
232-
host. Each independently callable HTTP/IPC boundary retains its own validation,
233-
signing policy, destination/identity binding, resource limits, cancellation and
234-
lifecycle ownership. Moving checks into shared frontend code is not a substitute
235-
for Rust enforcement. The relay remains the access-control authority.
236-
- For necessary cross-language implementations, share concrete contract cases
237-
rather than inventing a universal adapter or code generator. Existing JSON
238-
fixtures can be read by Vitest and Rust `include_str!`. Document intentional or
239-
unresolved differences with separate expected outcomes; neither implementation
240-
automatically defines the intended policy. Changing those outcomes is a behavior
241-
decision, not a refactor. Do not add a second source of feature policy in `dev/`.
236+
host. Shipped Rust IPC boundaries retain their own validation, signing policy,
237+
destination/identity binding, resource limits, cancellation and lifecycle
238+
ownership. Moving checks into shared frontend code is not a substitute for Rust
239+
enforcement. The relay remains the access-control authority. Existing broker
240+
endpoints keep their safety checks while they remain callable; this does not
241+
require a Node endpoint or signing-policy copy for a new feature.
242+
- **Frontend TypeScript checks + Rust enforcement:** both ship. Shared concrete
243+
contract cases are the long-term pattern for necessary cross-language logic,
244+
not a universal adapter or code generator. Existing JSON fixtures can be read by
245+
Vitest and Rust `include_str!`.
246+
- **`dev/` Node copy + Rust implementation:** only Rust ships. Shared cases are a
247+
temporary drift check until the Node copy is removed, not a reason to preserve
248+
or expand it. Document intentional or unresolved differences with separate
249+
expected outcomes; neither implementation automatically defines intended policy.
250+
Changing outcomes is a behavior decision, not a refactor. Do not add a second
251+
source of feature policy in `dev/`.
242252

243253
### Review and evidence
244254

@@ -249,25 +259,59 @@ same change. Reuse existing runners and CI; this is not an extra full-suite gate
249259
for each edit. Keep feature details with their owner, not copied into this guide.
250260

251261
[Canvas shape cases](../src/features/channel-templates/canvas-signing-contract.json)
252-
are consumed by the Node and Rust tests. They cover kind-40100 tag shape, including
253-
an explicitly rejected native deserialization case; each host separately tests the
254-
UTF-8 content limit. This is not whole endpoint parity: broker freshness checks,
255-
native serialized-event limits, HTTP/IPC authorization and publication outcomes
256-
are separate layers. Existing host-specific checks remain necessary.
257-
258-
Report the exact snapshot and host/mode exercised. A broker-backed browser fixture,
259-
or a Tauri window using that broker, does not prove native signing, OS storage,
260-
networking or filesystem behavior. Native/live acceptance needs an agreed isolated
261-
identity/data setup; browser fixtures and test identities must never use real keys.
262+
are a temporary Node/Rust mirror check, not a permanent dual-host contract. They
263+
cover kind-40100 tag shape, including an explicitly rejected native deserialization
264+
case; each host separately tests the UTF-8 content limit. This is not whole endpoint
265+
parity: broker freshness checks, native serialized-event limits, HTTP/IPC
266+
authorization and publication outcomes are separate layers. Existing host-specific
267+
checks remain necessary until the corresponding broker endpoint is retired; retain
268+
the Rust regression cases when removing the Node consumer.
269+
270+
**Manual testing of anything that ships uses `BUZZ_DEV_VIEWER= just desktop`.**
271+
The explicit empty value overrides a pin inherited from `.env.local`; merely
272+
unsetting the shell variable does not. This selects the shipped native code path,
273+
not the release credential namespace or a release bundle. Packaging, OS integration
274+
and release-specific behavior still need the appropriate packaged-build checks.
275+
Broker-backed runs, including pinned native windows, do not count as acceptance.
276+
They remain useful for browser diagnostics and existing broker tests, but do not
277+
prove native signing, OS storage, networking or filesystem behavior.
278+
279+
Report the exact snapshot and host/mode exercised. Native/live acceptance needs an
280+
agreed isolated identity/data setup; browser fixtures and test identities must
281+
never use real keys. Do not launch a native app or switch someone's active identity
282+
merely to follow this testing guidance.
283+
284+
### Broker reduction sequence
285+
286+
The following is the proposed removal order, not authorization to delete current
287+
browser workflows. Each slice must identify its callers, move needed regression
288+
coverage to the shipped owner, and delete displaced code in the same change. A
289+
whole broker endpoint/module can go only after its browser use is explicitly
290+
retired or replaced; do not weaken a still-callable endpoint to reduce duplication.
291+
292+
| Order | Existing `dev/` responsibility | Reduction and exit condition |
293+
| --- | --- | --- |
294+
| 1 | `user-status.mjs` | Remove repeated text/emoji policy in favor of the existing `src/features/relay` owner. Keep remaining broker shape/time enforcement only while its status endpoint is supported; do not copy it into Rust incidentally. |
295+
| 2 | `channel-kit.mjs`, `session-commands.mjs`, `direct-messages.mjs`, signing branches in `relay-broker.mjs` | Retire browser write capabilities one feature at a time after native acceptance and replacement fixture coverage. Remove each Node validator/encryption helper with its last caller; keep native signing tests. |
296+
| 3 | `read-state.mjs`, `sidebar-{preferences,mutes,sort,stars}.mjs` | Retire encrypted-state broker routes and their Node copies once browser callers no longer need them. Shared frontend edit policy and native custody remain. |
297+
| 4 | `agent-memory.mjs`, `agent-observer.mjs`, `archive.mjs`, `project-git.mjs`, `attachment-{file,upload}.mjs`, `media-preparation.mjs` | Remove feature-by-feature after archive/observer, repository and media browser uses are retired or replaced and native failure/recovery coverage is retained. Do not delete user data or migrate credentials as cleanup. |
298+
| 5 | `relay-broker.mjs` and its declaration | Remove residual routes and the custom stream bridge only after their consumers and broker-backed fixtures are retired or replaced. Any shared-transport replacement is a separate design decision, not an assumed prerequisite. |
299+
300+
Developer tools (`developer-settings.ts`, `live-setup-probe.mjs`) are not Rust
301+
feature mirrors. Legacy library and hosted-community helpers (`agent-library.mjs`,
302+
`builderlab.mjs`) need separate caller/capability decisions before removal; they
303+
are not automatically replaced by native identity. This sequence adds no new
304+
backend and changes no runtime defaults or credentials.
262305

263306
## Interactive product iteration
264307

265308
While shaping the first version, default to **edit → human tries the running app
266309
→ adjust**. A manual feedback handoff is not a review or shipping gate.
267310

268311
- Reuse the agreed development worktree and branch, with one owner of product
269-
edits. Keep one dev server running: `just web` for shared frontend work, or
270-
`just desktop` when native behavior matters. Vite handles supported frontend
312+
edits. Keep one dev server running: `BUZZ_DEV_VIEWER= just desktop` for manual
313+
testing of shipped behavior. `just web` remains useful for browser-only
314+
diagnostics and fixtures, not acceptance. Vite handles supported frontend
271315
updates without a package rebuild. State when a reload/restart is needed;
272316
coordinate native launches with the human rather than restarting their app.
273317
- Make small, coherent changes and hand them back as **ready to try**, naming

‎src-tauri/src/relay/tests.rs‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2155,12 +2155,14 @@ async fn preference_batches_reject_invalid_ciphertext_after_signature_verificati
21552155
}
21562156

21572157
#[test]
2158-
fn canvas_signing_shape_matches_broker_contract() {
2158+
fn canvas_signing_shape_matches_shared_contract() {
21592159
let cases: serde_json::Value = serde_json::from_str(include_str!(
21602160
"../../../src/features/channel-templates/canvas-signing-contract.json"
21612161
))
21622162
.unwrap();
2163-
for case in cases.as_array().unwrap() {
2163+
let cases = cases.as_array().unwrap();
2164+
assert!(!cases.is_empty(), "shared Canvas signing corpus is empty");
2165+
for case in cases {
21642166
// Tag shape plus EventTemplate deserialization, not IPC wiring, broker
21652167
// freshness, the native signing budget or publication.
21662168
let event = serde_json::from_value::<EventTemplate>(serde_json::json!({

0 commit comments

Comments
 (0)