diff --git a/.github/workflows/dogfood-gate.yml b/.github/workflows/dogfood-gate.yml index fc57290..221e19f 100644 --- a/.github/workflows/dogfood-gate.yml +++ b/.github/workflows/dogfood-gate.yml @@ -211,9 +211,15 @@ jobs: HAS_GROOVE_CODE="true" fi - # Check if this repo likely serves HTTP (has server/listener code) + # Check if this repo likely serves HTTP in production. Key on + # production HTTP-server framework markers only. A bare `TcpListener` + # is deliberately NOT a signal: it is dominated by test/utility use + # (e.g. a #[cfg(test)] loopback fake), so matching it produced a + # spurious groove nudge on client-only apps. A real hand-rolled Rust + # server still pairs the listener with `axum::serve`/`hyper::Server`, + # which are matched here. HAS_SERVER="false" - if grep -rl 'TcpListener\|Bandit\|Plug.Cowboy\|httpz\|vweb\|axum::serve\|actix_web' --include='*.rs' --include='*.ex' --include='*.zig' --include='*.v' . 2>/dev/null | head -1 | grep -q .; then + if grep -rl 'Bandit\|Plug.Cowboy\|httpz\|vweb\|axum::serve\|actix_web\|hyper::Server\|rocket::build\|warp::serve' --include='*.rs' --include='*.ex' --include='*.zig' --include='*.v' . 2>/dev/null | head -1 | grep -q .; then HAS_SERVER="true" fi diff --git a/.machine_readable/6a2/ECOSYSTEM.a2ml b/.machine_readable/6a2/ECOSYSTEM.a2ml index d0013d8..d3ca8c7 100644 --- a/.machine_readable/6a2/ECOSYSTEM.a2ml +++ b/.machine_readable/6a2/ECOSYSTEM.a2ml @@ -1,10 +1,42 @@ # SPDX-License-Identifier: MPL-2.0 # ECOSYSTEM.a2ml — Ecosystem position # Converted from ECOSYSTEM.scm on 2026-03-15 +# Enriched 2026-07-09: sibling-integration status + launcher carve-out, +# ground-truthed against cloned sibling repos. Full evidence in +# docs/governance/SIBLING-INTEGRATIONS.adoc. [metadata] project = "neurophone" ecosystem = "hyperpolymath" +version = "1.0.0" +last-updated = "2026-07-09" [position] type = "component" +role = "on-device Android neurosymbolic-AI app (sensor -> LSM -> ESN -> bridge -> LLM)" + +[related-projects] +# relationship in { dependency, dependent, sibling-standard, precedent, +# potential-consumer, not-applicable }. `status` is the ground-truthed +# integration state as of [metadata].last-updated. +projects = [ + { name = "gossamer", relationship = "dependency", status = "in-progress", note = "Android WebView/JNI runtime shell; Kotlin->Rust migration (#83). The Android surface targets gossamer, not Kotlin." }, + { name = "conative-gating", relationship = "dependency", status = "blocked-external", note = "GO/NO-GO egress veto in front of claude-client (#103); upstream Rust client not yet reachable in-session." }, + { name = "burble", relationship = "potential-consumer", status = "blocked-upstream", note = "BLE nearby-presence sensor, read-only consumer. Blocked on burble Phase 0 - wire manifest + Idris2 ABI + Android emitter do not yet exist; ADR-0010 Proposed. See docs/BT-PRESENCE-PLAN.adoc." }, + { name = "panll", relationship = "precedent", status = "precedent-only", note = "Migration precedent (Tauri->Gossamer). No runtime data flow; panll's live ingest path is panll<->panic-attack event-chains, not neurophone." }, + { name = "groove", relationship = "not-applicable", status = "not-applicable", note = "Runtime service-discovery protocol for HTTP services offering capabilities. neurophone runs no server and offers none." }, + { name = "cleave", relationship = "not-applicable", status = "not-applicable", note = "Pre-alpha design corpus; zero implementation, no ABI/schema/SDK, no domain overlap." }, + { name = "panic-attack", relationship = "dependency", status = "wired", note = "Static-analysis scanner run over neurophone's own source (Justfile, audits/)." }, + { name = "verisimdb", relationship = "potential-consumer", status = "design", note = "Scan-result hexad persistence (estate Records); not wired from neurophone." }, +] + +[integration-status] +# Durable record of the sibling-integration audit. Full evidence and +# EXISTS-vs-PLANNED tables in the governance doc below. +reference = "docs/governance/SIBLING-INTEGRATIONS.adoc" +ground-truthed = "2026-07-09" + +[carve-outs] +# Estate standards from which neurophone is a documented, justified exception. +# Authority + full rationale in docs/governance/SIBLING-INTEGRATIONS.adoc. +launcher-standard = { status = "carve-out", authority = "owner decision 2026-07-09", reason = "neurophone is an on-device Android app, not a desktop/server launcher target. The estate launcher standard assumes runtime.kind = 'server-url' (a localhost-bound process with a start command, pid-file, URL polling, and XDG .desktop / Start-Menu integration). None of that maps onto an APK, whose launch surface is the platform LAUNCHER intent in AndroidManifest.", ref = "docs/governance/SIBLING-INTEGRATIONS.adoc" } diff --git a/docs/BT-PRESENCE-PLAN.adoc b/docs/BT-PRESENCE-PLAN.adoc index ea8cf72..f4c0f78 100644 --- a/docs/BT-PRESENCE-PLAN.adoc +++ b/docs/BT-PRESENCE-PLAN.adoc @@ -12,6 +12,43 @@ cross-repo Bluetooth integration. This document covers only the neurophone side. ==== +[IMPORTANT] +==== +*Upstream status — BLOCKED (ground-truthed 2026-07-09 against burble @ `0926a15`).* + +NeuroPhone's Phase-2 work cannot begin: every burble-side artifact this plan +consumes is still design-only in burble, and burble has not completed its own +Phase 0. + +* `Burble.ABI.NearbyPresence` (Idris2 wire type) — *absent* from burble's ABI + directory and from its `burble-abi.ipkg` module list; it appears only as a + planned "NEW" line in burble's `ANDROID-CLIENT.adoc`. +* `nearby-presence.a2ml` (wire format) — *does not exist* in burble, at any path. +* burble's Android client (which must emit the advertisement) — *does not exist* + (`client/android/` is absent; burble's doc says "Design only — no code yet"). +* burble `docs/decisions/0010-presence-discovery-and-trust-zones.adoc` is + `Status: Proposed` (2026-07-08) and states "Nothing here is built yet"; there + is no defined advertisement UUID or byte layout — only a prose knock-packet + sketch, explicitly *not* a continuous advertisement. + +No NeuroPhone codegen or vendored schema can be created against a format that has +never been authored. This plan resumes when burble authors and freezes the +advertisement format. Full audit: link:governance/SIBLING-INTEGRATIONS.adoc[SIBLING-INTEGRATIONS.adoc]. + +*Path correction.* Earlier revisions of this doc pointed the codegen at +`burble/.machine_readable/6a2/nearby-presence.a2ml`. That was wrong: `6a2/` is +*NeuroPhone's* machine-readable namespace, not burble's. burble's planned +location is `.machine_readable/descriptiles/nearby-presence.a2ml`. The citations +below have been corrected. + +*Toolchain correction.* The Kotlin scanner files in the file-by-file plan below +(`*.kt`) predate the gossamer Android migration (#83) and NeuroPhone's current +language policy, which bans Kotlin/Java for mobile. When burble unblocks, the +Android-side scanner must be expressed through the gossamer surface (Rust/JNI), +not reintroduced as Kotlin. The `.kt` entries are retained only as a +functional sketch of the scanner's responsibilities. +==== + == Scope NeuroPhone gains a Bluetooth Low Energy *presence sensor* that feeds the existing @@ -36,7 +73,7 @@ Burble owns the wire protocol and the voice client. NeuroPhone owns only the con |=== | Lives in burble | Lives in neurophone -| `.machine_readable/6a2/nearby-presence.a2ml` (wire format) +| `.machine_readable/descriptiles/nearby-presence.a2ml` (wire format) — _planned in burble; not yet authored_ | `crates/bt-presence/` (scanner + decoder + decay) | `src/Burble/ABI/NearbyPresence.idr` (Idris2 type) @@ -51,6 +88,8 @@ Burble owns the wire protocol and the voice client. NeuroPhone owns only the con The neurophone build pulls the a2ml manifest from burble at build time (via `crates/bt-presence/build.rs` codegen) — single source of truth, no protocol fork. +_(Blocked: the manifest does not yet exist in burble — see the Upstream status +note above.)_ == File-by-file plan @@ -118,7 +157,7 @@ NeuroPhone work begins at Phase 2 in the cross-repo plan: * link:../README.adoc[README.adoc] — privacy commitments to preserve. * link:../TOPOLOGY.adoc[TOPOLOGY.adoc] — existing sensor → LSM → ESN → bridge pipeline diagram. * `burble/docs/architecture/ANDROID-CLIENT.adoc` — authoritative cross-repo plan. -* `burble/.machine_readable/6a2/nearby-presence.a2ml` — wire format that codegen reads. +* `burble/.machine_readable/descriptiles/nearby-presence.a2ml` — wire format that codegen reads (planned in burble; not yet authored). == Memory pointer diff --git a/docs/governance/SIBLING-INTEGRATIONS.adoc b/docs/governance/SIBLING-INTEGRATIONS.adoc new file mode 100644 index 0000000..8aa8a02 --- /dev/null +++ b/docs/governance/SIBLING-INTEGRATIONS.adoc @@ -0,0 +1,222 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += NeuroPhone — Sibling-Integration Status +:toc: preamble +:toclevels: 3 + +[NOTE] +==== +*Purpose.* This document is the authoritative, ground-truthed record of how +NeuroPhone relates to four sibling repositories that a repo audit flagged as +"not integrated" — `groove`, `cleave`, `burble`, `panll` — plus the estate +*launcher standard* carve-out. It exists so those rows stop reading as +unexplained compliance gaps: each is either genuinely *not applicable*, +*precedent-only*, or *blocked on upstream work that does not yet exist*. + +*Method.* Each disposition below was verified against the sibling repository's +own source at the commit noted, not against design docs or memory. Where a +NeuroPhone-side doc previously asserted an integration artifact, the assertion +was checked against the upstream file it names. "EXISTS" means the artifact is +present in the upstream tree today; "PLANNED" means it appears only in an +upstream design doc. + +*Ground-truthed:* 2026-07-09. +==== + +== Summary + +[cols="1,2,3",options="header"] +|=== +| Sibling | Classification | One-line disposition + +| `groove` +| NOT-APPLICABLE +| Runtime service-discovery protocol for HTTP services that offer capabilities. NeuroPhone runs no server and offers none. + +| `cleave` +| NOT-APPLICABLE +| Pre-alpha design corpus — zero implementation, no ABI/schema/SDK, no domain overlap. + +| `burble` +| BLOCKED (upstream Phase 0) +| Real future integration (BLE nearby-presence sensor), but every burble-side artifact NeuroPhone would consume is still design-only. + +| `panll` +| PRECEDENT-ONLY +| Migration precedent (Tauri→Gossamer). No runtime data flow; panll's live ingest path is panll↔panic-attack, not panll↔neurophone. + +| launcher standard +| CARVE-OUT +| NeuroPhone is an Android app, not a desktop/server launcher target. The standard assumes a `server-url` runtime. +|=== + +The honest conclusion of the integration audit is that *none of the four is +buildable today*: three are not-applicable or precedent-only by nature, and the +one genuinely-substantive integration (`burble`) is blocked on `burble` +completing its own unfinished Phase 0. Creating integration code for any of them +now would be fabrication, not wiring. + +== groove — NOT-APPLICABLE + +*What it is.* A runtime service-discovery + capability-negotiation protocol +(working draft v0.2.0, grade C+). Every groove-aware system MUST expose +`GET /.well-known/groove` returning a manifest that advertises the capabilities +it `offers` and `consumes`; peers probe local ports and compose. + +*Why NeuroPhone is out of scope.* NeuroPhone is a read-only, on-device Android +app. It runs no HTTP server and offers no local capability to peer processes. +The groove spec is explicit that this places it outside the protocol: a manifest +with zero capabilities "SHOULD be flagged by tooling: a service that offers +nothing has no reason to speak Groove" (groove `spec/SPEC.adoc` §2.1.1). There is +also no Rust client SDK to call: `clients/` is JavaScript-only, and the +`groove-core` Rust library the README references does not exist in the tree +(removed per groove ADR 0001). Rust bindings are listed only as an aspiration. + +*Disposition.* No groove manifest, no groove code. NeuroPhone's +`.github/workflows/dogfood-gate.yml` `groove-check` job is *advisory* (emits a +non-blocking `::warning::`, never fails) and only fires when a repo has server +code but no manifest — which NeuroPhone does not. + +[NOTE] +==== +*Fixed defect (this change).* The `has_server` heuristic in `groove-check` +grepped for a bare `TcpListener`, which matched NeuroPhone's *test-only* fake +Claude server (`crates/claude-client/src/lib.rs`, inside a `#[cfg(test)]` +module). That could surface a spurious — though non-blocking — groove warning in +CI summaries. The detector now keys on production HTTP-server framework markers +(`axum::serve`, `actix_web`, `hyper::Server`, `Bandit`, `Plug.Cowboy`, …), which +a test loopback listener does not trip. The same fix was made at source in +`rsr-template-repo`, the template this workflow is copied from. +==== + +== cleave — NOT-APPLICABLE + +*What it is.* A design corpus / draft specification for a proposed Rust +"transmutable interface-engine" library. Its own status line: "Design corpus. +ZERO lines of cleave-specific implementation exist. 0 of 7 proofs done" +(cleave `README.adoc`). + +*Why NeuroPhone is out of scope.* There is nothing to integrate against — no +crate, no header, no ABI, no wire format, no schema, no client SDK. cleave +explicitly delegates wire encoding to `weft` and protocol/manifest handshake to +`groove`, so even its aspirational "unified protocol endpoint" does not live in +the repo. A repo-wide search for NeuroPhone's domain terms (sensor, reservoir, +LSM/ESN, bluetooth, presence, android, on-device LLM) returns no matches. + +*Disposition.* No integration point exists or is planned. The only conceivable +future tie is a conceptual analogy between cleave's (unbuilt) FFI-dial "kernel" +and NeuroPhone's JNI/FFI boundary — an analogy, not an integration, and it +cannot be specified until cleave writes its kernel. + +== burble — BLOCKED (upstream Phase 0 incomplete) + +*What it is.* A self-hostable voice-first communications platform. Relevant to +NeuroPhone only via a planned Bluetooth Low Energy *nearby-presence* signal that +NeuroPhone would consume read-only as one more sensor input (see +`docs/BT-PRESENCE-PLAN.adoc`). NeuroPhone's work begins at the cross-repo plan's +Phase 2 and depends on burble finishing Phases 0–1 first. + +*Ground truth — every consumed artifact is still PLANNED, not present:* + +[cols="2,3,1",options="header"] +|=== +| Artifact NeuroPhone's plan names | Reality in `burble` @ `0926a15` | Status + +| `src/Burble/ABI/NearbyPresence.idr` (Idris2 wire type) +| Absent from the ABI dir and from the `burble-abi.ipkg` module list; appears only as a "NEW" line in `docs/architecture/ANDROID-CLIENT.adoc` +| PLANNED + +| `nearby-presence.a2ml` (wire format) +| Does not exist. NeuroPhone's plan cited `.machine_readable/6a2/…` — but `6a2/` is *NeuroPhone's* namespace; burble uses `descriptiles/`, and the file is absent there too +| PLANNED (+ wrong path) + +| burble Android client emitting the advertisement (Phase-1 precondition) +| No `client/android/` exists; `ANDROID-CLIENT.adoc`: "Design only — no code yet" +| PLANNED + +| `server/lib/burble/bridges/neurophone.ex` +| No `bridges/` directory exists +| PLANNED + +| Defined advertisement UUID / byte layout +| None defined anywhere; only a prose knock-packet sketch, explicitly *not* a continuous advertisement +| UNDEFINED +|=== + +The governing decision, burble `docs/decisions/0010-presence-discovery-and-trust-zones.adoc`, +is `Status: Proposed` (dated 2026-07-08) and states "Nothing here is built yet." +burble's own `PRODUCTION-BLOCKER-HANDOFF.adoc` flags the Android BLE design as +internally contradictory and unbuilt. + +*Disposition.* The honest NeuroPhone-side artifact today is a *blocked-on note*, +not codegen and not a vendored schema — you cannot vendor or generate against a +wire format that has never been authored. `docs/BT-PRESENCE-PLAN.adoc` has been +annotated with this upstream status and two corrections (the `6a2/`→`descriptiles/` +path error, and the now-superseded Kotlin scanner plan, which must follow the +gossamer migration per #83 rather than reintroduce banned Kotlin). NeuroPhone +resumes Phase 2 the moment burble authors and freezes the advertisement format. + +== panll — PRECEDENT-ONLY + +*What it is.* A cognitive-relief, multi-pane "Human-Things Interface" desktop +panel host (ReScript/TEA front end; Rust + Gossamer back end). Event-chain +viewing is *one* panel feature, not its identity. + +*Why the relationship is precedent, not runtime.* The only relationship asserted +in either repo's code or docs is a *migration precedent*: panll migrated +`src-tauri/` → `src-gossamer/` (desktop only), and NeuroPhone's RFC cites that as +the template for its own Kotlin→Rust Android migration +(`docs/migrations/RFC-ANDROID-KOTLIN-TO-RUST.adoc`). No runtime data flow is +claimed anywhere. panll's one *live* data-ingest path is panll↔`panic-attack` +event-chain JSON (`src/core/EventChain.res`), and in NeuroPhone `panic-attack` is +only ever run as a scanner over NeuroPhone's own source — NeuroPhone emits no +event chains. + +*Latent (design-only) options, none built.* panll offers three extension +surfaces — a `DatabaseModule` ReScript protocol (internal, compile-time), a +groove endpoint (fixed consumed-capability set), and a design-phase "transmutable +panel" clade `.a2ml`. A future NeuroPhone↔panll link could ride any of them +(e.g. NeuroPhone exporting `panic-attack`-shaped event-chain JSON that panll's +Pane-W could load), but no NeuroPhone-side artifact for it exists today. + +*Disposition.* Recorded as precedent-only. No action required unless a runtime +integration is later commissioned. + +== Launcher standard — CARVE-OUT + +*The standard.* The estate launcher standard +(`standards/launcher/launcher-standard.a2ml` + `docs/UX-standards/launcher-standard.adoc`) +describes a *desktop/server* application launcher. Its load-bearing assumption is +`[runtime].kind = "server-url"`: a long-running local process bound to a +`localhost` port, started by a shell `command`, tracked by a `pid-file`, and +polled until its `url` responds (`wait-for-url-timeout-seconds`) — after which it +opens a browser. Its `--integ`/`--disinteg` modes install XDG `.desktop` files, +Start-Menu/Applications entries, and desktop icons on Linux/macOS/Windows. The +reference descriptor `burble.launcher.a2ml` is exactly this shape +(`kind = "server-url"`, port 4020, `mix phx.server`, XDG desktop categories). + +*Why NeuroPhone is a carve-out.* NeuroPhone is an on-device Android application +(Rust workspace + JNI/Android surface). It has *no* server URL, no `localhost` +port, no shell start `command`, no pid-file, and no desktop entry. An Android +app's launch surface is the platform `LAUNCHER` intent declared in +`AndroidManifest.xml` (`MainActivity` with `android.intent.action.MAIN` + +`android.intent.category.LAUNCHER`) — provided by the OS, not by an estate +launcher script. None of the `[runtime]` fields the standard requires can be +populated for an APK. + +*Scope of the standard.* The standard is provisioned by `launch-scaffolder` for +repos that ship a desktop/server app, and its lock-step CI gate runs only inside +`standards` itself — it does not scan consumer repos. So this carve-out is a +documentation/audit disposition, not a suppressed CI failure. + +*Disposition.* NeuroPhone is out of scope for the desktop/server launcher +standard, by owner decision (2026-07-09). Recorded machine-readably in +`.machine_readable/6a2/ECOSYSTEM.a2ml` `[carve-outs]`. If NeuroPhone ever ships a +companion *desktop* control panel, that component — not the APK — would adopt the +standard. + +== See also + +* link:../BT-PRESENCE-PLAN.adoc[BT-PRESENCE-PLAN.adoc] — the burble presence-sensor plan, now annotated with upstream status. +* link:../migrations/RFC-ANDROID-KOTLIN-TO-RUST.adoc[RFC-ANDROID-KOTLIN-TO-RUST.adoc] — the panll migration precedent. +* `../../.machine_readable/6a2/ECOSYSTEM.a2ml` — machine-readable related-projects + carve-outs.