@qvac/core 0.1.4 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/.claude/skills/asana/SKILL.md +86 -0
  2. package/.claude/skills/compaction/SKILL.md +127 -0
  3. package/.claude/skills/device-mesh-debug/SKILL.md +328 -0
  4. package/.claude/skills/gh-stack/SKILL.md +181 -0
  5. package/.claude/skills/gh-stack/references/commands.md +177 -0
  6. package/.claude/skills/gh-stack/references/stack-design.md +97 -0
  7. package/.claude/skills/gh-stack/references/troubleshooting.md +159 -0
  8. package/.claude/skills/js-house-style/SKILL.md +670 -0
  9. package/.claude/skills/pr-create/SKILL.md +180 -0
  10. package/.claude/skills/pr-review/SKILL.md +216 -0
  11. package/CLAUDE.md +45 -0
  12. package/README.md +10 -5
  13. package/dist-lib/lib/api/agents.js +3 -3
  14. package/dist-lib/lib/api/chat-groups.d.ts +1 -1
  15. package/dist-lib/lib/api/chat-groups.js +5 -3
  16. package/dist-lib/lib/api/chat.js +2 -2
  17. package/dist-lib/lib/api/current-mesh.d.ts +3 -2
  18. package/dist-lib/lib/api/current-mesh.js +4 -3
  19. package/dist-lib/lib/api/devices.js +1 -0
  20. package/dist-lib/lib/api/index.js +2 -0
  21. package/dist-lib/lib/api/members.d.ts +3 -0
  22. package/dist-lib/lib/api/members.js +23 -0
  23. package/dist-lib/lib/api/mesh.d.ts +14 -3
  24. package/dist-lib/lib/api/mesh.js +20 -3
  25. package/dist-lib/lib/api/watchable.d.ts +1 -1
  26. package/dist-lib/lib/api/watchable.js +1 -1
  27. package/dist-lib/lib/assistant.js +2 -1
  28. package/dist-lib/lib/core/agent.d.ts +1 -0
  29. package/dist-lib/lib/core/agent.js +29 -1
  30. package/dist-lib/lib/core/chat-group.d.ts +4 -0
  31. package/dist-lib/lib/core/chat-group.js +43 -1
  32. package/dist-lib/lib/core/chat.d.ts +10 -0
  33. package/dist-lib/lib/core/chat.js +75 -9
  34. package/dist-lib/lib/core/contract/index.js +2 -0
  35. package/dist-lib/lib/core/contract/joined-meshes.d.ts +2 -0
  36. package/dist-lib/lib/core/contract/joined-meshes.js +41 -0
  37. package/dist-lib/lib/core/contract/members.js +68 -2
  38. package/dist-lib/lib/core/contract/writers.js +19 -3
  39. package/dist-lib/lib/core/departures.d.ts +3 -1
  40. package/dist-lib/lib/core/departures.js +6 -4
  41. package/dist-lib/lib/core/device-attestation.d.ts +8 -0
  42. package/dist-lib/lib/core/device-attestation.js +25 -0
  43. package/dist-lib/lib/core/device-invites.d.ts +9 -0
  44. package/dist-lib/lib/core/device-invites.js +40 -0
  45. package/dist-lib/lib/core/files/index.d.ts +2 -1
  46. package/dist-lib/lib/core/files/index.js +1 -1
  47. package/dist-lib/lib/core/files/store/index.d.ts +1 -0
  48. package/dist-lib/lib/core/files/store/server.d.ts +5 -4
  49. package/dist-lib/lib/core/files/store/server.js +10 -6
  50. package/dist-lib/lib/core/helpers/index.d.ts +1 -1
  51. package/dist-lib/lib/core/hosted-agents.d.ts +3 -1
  52. package/dist-lib/lib/core/hosted-agents.js +9 -3
  53. package/dist-lib/lib/core/identity.d.ts +10 -0
  54. package/dist-lib/lib/core/identity.js +45 -0
  55. package/dist-lib/lib/core/invite.d.ts +3 -0
  56. package/dist-lib/lib/core/invite.js +8 -2
  57. package/dist-lib/lib/core/local/index.d.ts +22 -7
  58. package/dist-lib/lib/core/local/index.js +202 -66
  59. package/dist-lib/lib/core/membership.d.ts +8 -2
  60. package/dist-lib/lib/core/membership.js +33 -9
  61. package/dist-lib/lib/core/mesh-seed-handoff.d.ts +17 -0
  62. package/dist-lib/lib/core/mesh-seed-handoff.js +34 -0
  63. package/dist-lib/lib/core/mesh.d.ts +13 -1
  64. package/dist-lib/lib/core/mesh.js +61 -8
  65. package/dist-lib/lib/core/migrations/index.d.ts +3 -1
  66. package/dist-lib/lib/core/migrations/index.js +2 -2
  67. package/dist-lib/lib/core/migrations/membership.js +27 -15
  68. package/dist-lib/lib/core/rank.d.ts +14 -0
  69. package/dist-lib/lib/core/rank.js +23 -0
  70. package/dist-lib/lib/core/sync/index.js +6 -0
  71. package/dist-lib/lib/core.d.ts +91 -13
  72. package/dist-lib/lib/core.js +1051 -207
  73. package/dist-lib/schema/build.js +3 -2
  74. package/dist-lib/schema/engine.js +153 -9
  75. package/dist-lib/schema/field-order.js +4 -1
  76. package/dist-lib/schema/local.js +32 -0
  77. package/dist-lib/schema/qvac.js +45 -6
  78. package/dist-lib/spec/bind.js +35 -0
  79. package/dist-lib/spec/calls.js +37 -27
  80. package/dist-lib/spec/capabilities.d.ts +30 -10
  81. package/dist-lib/spec/hrpc/hrpc.json +135 -5
  82. package/dist-lib/spec/hrpc/index.js +130 -9
  83. package/dist-lib/spec/hrpc/messages.js +408 -14
  84. package/dist-lib/spec/hyperschema/index.js +408 -14
  85. package/dist-lib/spec/hyperschema/schema.json +309 -1
  86. package/dist-lib/spec/hyperschema/types.d.ts +90 -1
  87. package/dist-lib/spec/local/hyperdb/db.json +46 -1
  88. package/dist-lib/spec/local/hyperdb/index.js +209 -2
  89. package/dist-lib/spec/local/hyperdb/messages.js +557 -90
  90. package/dist-lib/spec/local/hyperschema/index.js +240 -2
  91. package/dist-lib/spec/local/hyperschema/schema.json +120 -1
  92. package/dist-lib/spec/local/hyperschema/types.d.ts +33 -1
  93. package/dist-lib/spec/mesh/hyperdb/db.json +16 -1
  94. package/dist-lib/spec/mesh/hyperdb/index.js +71 -2
  95. package/dist-lib/spec/mesh/hyperdb/messages.js +571 -192
  96. package/dist-lib/spec/mesh/hyperdispatch/dispatch.json +13 -1
  97. package/dist-lib/spec/mesh/hyperdispatch/index.js +35 -1
  98. package/dist-lib/spec/mesh/hyperdispatch/messages.js +283 -20
  99. package/dist-lib/spec/mesh/hyperschema/index.js +283 -20
  100. package/dist-lib/spec/mesh/hyperschema/schema.json +179 -1
  101. package/dist-lib/spec/mesh/hyperschema/types.d.ts +45 -1
  102. package/package.json +6 -6
  103. package/tui/app.mjs +416 -50
  104. package/tui/boot.mjs +1 -1
  105. package/tui/lib/sidebar.mjs +3 -2
@@ -0,0 +1,86 @@
1
+ ---
2
+ name: asana
3
+ description: Conventions for the QVAC Assistant Asana board when working through the Asana MCP server — what the MCP cannot do and what that silently breaks, the Context field that decides whether a task is visible at all, and the rule against consuming task descriptions. Use before creating, moving, or reading any Asana task for this project.
4
+ ---
5
+
6
+ # Asana — QVAC Assistant board
7
+
8
+ Asana work here goes through the **Asana MCP server**. This skill is not a tool;
9
+ it is the handful of things the MCP does not tell you and will not stop you
10
+ getting wrong.
11
+
12
+ - Workspace `45238840754660` (tether.to)
13
+ - Project `1214754188814246` (QVAC Assistant)
14
+ - Board: <https://app.asana.com/1/45238840754660/project/1214754188814246>
15
+
16
+ ## Do not create tasks through the MCP
17
+
18
+ `asana_create_task` takes `resource_subtype` of only `default_task`, `milestone`
19
+ or `approval`, and neither it nor `asana_update_task` accepts `custom_type` or
20
+ `custom_type_status_option`. This board runs on the **QVAC Basic Task** custom
21
+ type (`1214533632534265`), whose status options _are_ the workflow — the project
22
+ has one real section and tracks status entirely through the custom type.
23
+
24
+ So an MCP-created task is a plain default task that:
25
+
26
+ - is not a `QVAC Basic Task`,
27
+ - has no status (To Do / In Progress / In Code Review / Blocked /
28
+ Completed-Ready for QA / Fully Verified / Closed-Won't Fix), and
29
+ - cannot be given one afterwards through the API.
30
+
31
+ It lands on the board looking almost right and is undriveable. **Ask the user to
32
+ create the task in the Asana UI**, where the custom type is the default, and then
33
+ use the MCP to fill fields or comment on it. Do not create it yourself and
34
+ promise to "fix the type later" — the API has no route to do that.
35
+
36
+ Moving a task's status has the same limitation: the status lives on
37
+ `custom_type_status_option`, which the MCP cannot set. Status changes are a UI
38
+ action.
39
+
40
+ ## Context is mandatory, and the MCP will not warn you
41
+
42
+ The project's Dev Board tabs are saved views filtered on the **Context** custom
43
+ field. A task with Context unset appears only in "Full List" and "Overview" — it
44
+ is invisible on every Dev Board tab and silently slips off the team's radar.
45
+
46
+ Whenever you set fields on a task, set Context. Field `1214754188814251`:
47
+
48
+ | Value | GID | For |
49
+ | -------------- | ------------------ | ------------------------------------------------- |
50
+ | `harness` | `1214754188814252` | engine, mesh and sync, storage, build and release |
51
+ | `integrations` | `1214754188814253` | assistant runtime, agents, tools, skills |
52
+ | `other` | `1214758268571416` | genuinely cross-cutting: org, legal, product docs |
53
+
54
+ Surface which one you picked and why, and let the user correct it. Never guess
55
+ silently, and never leave it blank to avoid choosing.
56
+
57
+ ## Release grouping
58
+
59
+ Each Dev Board tab groups by **QVAC Workbench Release** (field
60
+ `1214111405360914`) first. A task with none lands in an "Untitled" bucket at the
61
+ bottom of every tab. Default to `tbc` (`1214757840453965`) when the release is
62
+ undecided.
63
+
64
+ **That field is the app's release, not a package version.** `@qvac/harness`,
65
+ `@qvac/core` and `@qvac/skills` each ship their own `0.x` line; putting one of
66
+ those numbers here files the task against a release that does not exist.
67
+
68
+ ## Never consume task descriptions
69
+
70
+ Work from task metadata only: GID, name, permalink, completion state, assignee,
71
+ memberships, custom fields, custom type and status, timestamps, and comments.
72
+
73
+ - `asana_get_task` returns the description by default. Pass an explicit
74
+ `opt_fields` list that omits `notes`, `html_notes` and `description`.
75
+ - Do not use Asana full-text search as a fallback — it matches descriptions.
76
+ Find tasks by the QVAC custom field (`1209150993228635`, text) or by GID.
77
+ - If the user wants you to act on a description, ask them to paste the relevant
78
+ excerpt rather than fetching it.
79
+
80
+ ## Before any mutation
81
+
82
+ Show the exact change and wait for a yes. That includes field edits, comments and
83
+ completion — this board is shared with the whole team, and a comment cannot be
84
+ unsent.
85
+
86
+ Never put tokens, secrets or internal-only URLs in a task or comment.
@@ -0,0 +1,127 @@
1
+ ---
2
+ name: compaction
3
+ description: Reason about prompt compaction (the fold), chat history and KV-cache invalidation in @qvac/core — why history is never evicted client-side, what compactChat is allowed to do, and which events must delete a chat's cache key. Read this BEFORE proposing any history windowing, trimming, token budgeting or "the model forgot the conversation" fix.
4
+ ---
5
+
6
+ # Compaction + cache invalidation
7
+
8
+ This repo owns the **prompt**: what history a run is given, when that history is
9
+ folded, and when a chat's cache key has to be thrown away. The **cache itself** —
10
+ the `kvCache` key, the context window, the overflow ladder, `ContextOverflowError`
11
+ — belongs to `@qvac/harness`; read its **kvcache** skill and
12
+ `@qvac/harness → docs/kvcache-reference.md` before changing anything on this side.
13
+
14
+ ## The rule that governs everything here
15
+
16
+ Three state sets exist and are **never reconciled**:
17
+
18
+ | Layer | State | Keyed by |
19
+ | --------- | -------------------------------------------------------- | --------------- |
20
+ | this repo | the message **list** (shrinks only on an overflow retry) | chat |
21
+ | SDK | the message **count** (`savedCount`) | cache file path |
22
+ | addon | token **positions** + the on-disk `.bin` | cache key |
23
+
24
+ `savedCount` means "already sent", never "still resident": nothing below the SDK
25
+ reports what it evicted. So **anything that quietly removes messages from the
26
+ middle of the history is a correctness bug, not an optimisation** — the model
27
+ loses that span with no signal anywhere. That is what killed the retired sliding
28
+ window, and it is the test any new idea has to pass.
29
+
30
+ **No client-side token math, ever.** Use the SDK's real `cacheTokens` /
31
+ `promptTokens` from `completion()` stats, and react to the typed
32
+ `ContextOverflowError`. Never estimate chars-per-token, never reserve a response
33
+ budget.
34
+
35
+ ## Before proposing history eviction
36
+
37
+ Ask whether the SDK cache already handles it. It does, for ordinary history
38
+ growth. The cases that genuinely need handling here are a message (or tool
39
+ result) larger than `ctx_size`, and the cross-device cold start — the cache is
40
+ device-local, so a chat that moves to another device legitimately re-primes.
41
+
42
+ **Compaction is the one sanctioned exception, and it already exists — do not
43
+ build a second one.** [`lib/compaction.ts`](../../../lib/compaction.ts) folds a
44
+ chat's older turns into one summary turn, persisted as a replicated `compaction`
45
+ chunk so every device rebuilds the same prompt; `historyFromChunks` in
46
+ [`lib/assistant.ts`](../../../lib/assistant.ts) applies it.
47
+
48
+ What makes the fold legal under the rule above:
49
+
50
+ - **It evicts from the prompt, never from the KV.** The chunks it folds stay in
51
+ the store and keep rendering; only what `completion()` is sent shrinks.
52
+ - **No token math.** The triggers read the SDK's own `cacheTokens` against the
53
+ `ctxSize` of the run that reported them, and the summary is bounded by prompt
54
+ shape rather than a computed budget.
55
+ - **It is a divergence writer, so it invalidates.** `compactChat` deletes the
56
+ chat key after the fold lands, and each device deletes once for a fold that
57
+ arrived from another one (`_reconcileCompaction`).
58
+ - **It has a floor.** Below `COMPACTION_MIN_CTX_SIZE` (4,096, in
59
+ [`lib/model-context.ts`](../../../lib/model-context.ts)) a fold cannot pay for
60
+ the ~420-token prefix it shares the window with, so those chats stay on the
61
+ harness overflow ladder. A client must read that constant before promising a
62
+ summary — the context picker still offers 1k and 2k.
63
+ - **It keeps one turn, and refuses to grow the prompt.** `COMPACTION_KEEP_TURNS`
64
+ is 1: the last user message stays verbatim because nothing else can answer it,
65
+ and a second kept turn would drag its assistant answer — usually the biggest
66
+ thing in the chat — along with it. `foldReducesPrompt` then refuses any summary
67
+ longer than the turns it replaces.
68
+ - **It narrows instead of failing.** The fold's own prompt is the range it folds,
69
+ so on a summarizer overflow `compactChat` halves the range and retries; a
70
+ boundary no later than the last fold's is refused, so it cannot un-fold a chat.
71
+ The boundary also walks back over the uploads bound to the first kept message,
72
+ which are appended before it.
73
+ - **The summarizing run is tool- and skill-less and passes no `cacheKey`**, so it
74
+ cannot answer the question instead of summarizing it, and cannot pollute the
75
+ chat's own cache file.
76
+
77
+ Triggers: proactively before a run on the previous round's numbers, at the end of
78
+ a run that filled the window itself, and reactively once the harness overflow
79
+ ladder is exhausted. All three announce a `compacting` phase, which clients must
80
+ exempt from any restart rule that discards a streamed answer on a non-terminal
81
+ status. Clearing the phase stays conditional — only the before-run fold does it,
82
+ because its run carries on.
83
+
84
+ After the fact the fold is visible from its chunk (`thread.compactionMarkers`,
85
+ anchored before the user message the fold precedes). Only the device that ran the
86
+ turn is a valid reading: `ctxSize` is per-device, so a chat that moved from a
87
+ phone carries a window this host does not have.
88
+
89
+ ## Invalidation — when the chat key must die
90
+
91
+ [`lib/kv-cache-reclaim.ts`](../../../lib/kv-cache-reclaim.ts) owns the keys:
92
+ `chatKvCacheKey(chatId)` and `chatRepairKvCacheKey(chatId, acceptedRepairs)` — a
93
+ repair generation nests under the chat key, so deleting the chat key reclaims
94
+ every generation.
95
+
96
+ This repo deletes a chat's cache at three moments, and **a new feature that
97
+ changes history in place must route through the same invalidation**:
98
+
99
+ 1. Before executing a superseding run — retry or regenerate, the `parentId`
100
+ run-request.
101
+ 2. When a chat disappears from the chat list (`disappearedChatIds`).
102
+ 3. For an agent's chats when its re-key fields change — bio, model, ctx,
103
+ kv-quant, tool and skill selection (`agentRekeyFingerprint`).
104
+
105
+ A future edit-message or delete-message feature is exactly case 1 in disguise.
106
+ Editing text that is already in the KV without dropping the key leaves the model
107
+ answering the _old_ text, invisibly.
108
+
109
+ Apps delete device-locally through the engine API: `clearKvCache()` and
110
+ `deleteChatKvCache({ id })` in [`lib/api/`](../../../lib/api/). Neither
111
+ replicates — the chat's warm cache may live on the provider device.
112
+
113
+ ## Symptoms, and where they actually come from
114
+
115
+ | Symptom | Look here first |
116
+ | --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
117
+ | "the model forgot the middle of the chat" | something evicted history without invalidating — never the cache doing its job |
118
+ | "it answers the question I asked an hour ago" | a stale cache key that should have been deleted (retry/regenerate, agent re-key) |
119
+ | every turn is slow to first token | `configHash` churn — a volatile system prompt or a changing tool set re-keys the file each turn |
120
+ | a long chat errors instead of folding | `ctxSize` below `COMPACTION_MIN_CTX_SIZE`; the fold is refused by design |
121
+ | the summary is longer than what it replaced | `foldReducesPrompt` refused it — that is the guard working |
122
+
123
+ ## Sibling skills
124
+
125
+ - The cache, the context window and the overflow ladder → **kvcache**, in
126
+ `@qvac/harness`.
127
+ - How the code itself should be shaped → **js-house-style**.
@@ -0,0 +1,328 @@
1
+ ---
2
+ name: device-mesh-debug
3
+ description: Diagnose, reproduce, fix and verify mobile + mesh bugs on a device or iOS simulator, driving a real phone against a scriptable bare mesh peer built on this repo's Core. Pairs adb/idb (launch, logs, screenshots, UI driving, and creating a simulator when none exists) with a peer that mints/joins a mesh and grows its oplog on command, so "the phone is behind" states can be produced deliberately. Use for on-device hangs, slow boots, sync gaps, or anything that only shows up against a busy mesh.
4
+ ---
5
+
6
+ # On-device mobile + mesh debugging
7
+
8
+ Mesh bugs cannot be reproduced from a unit test alone: they need a real device
9
+ and a real peer that is _ahead_ of it. `adb` and `idb` give you the device. This
10
+ repo's `examples/` give you the other side.
11
+
12
+ The mesh peer is a real `Core` from this repo on the **public DHT** — the same
13
+ class the app runs — driven over stdin. Not a mock, not a testnet.
14
+
15
+ > The **app** under test is built from `tetherto/qvac-app` (Expo/React Native),
16
+ > which is where the build commands below run. The **peer, the device driver and
17
+ > the scenarios** are here. That split is the only reason a section below talks
18
+ > about a directory this repo does not contain.
19
+
20
+ Both platforms go through one interface. `QVAC_TARGET=android` (default) uses
21
+ `adb`; `QVAC_TARGET=ios` uses `idb` plus `simctl`, and **provisions a simulator
22
+ when there is none** — a machine whose `~/Library/Developer/CoreSimulator/Devices`
23
+ has been pruned lists dozens of devices that all fail to boot with "The device's
24
+ data is no longer present", so `ensureTarget()` prunes and creates one.
25
+
26
+ ## The loop
27
+
28
+ 1. **Reproduce on device first**, and capture the log window that brackets the
29
+ symptom. Do not theorise from source before you have a timestamped trace.
30
+ 2. **Narrow to a unit test.** Once you can name the blocking call, reproduce it
31
+ in `test/basic/` — a device repro is evidence, a test is a regression guard.
32
+ The sharpest shape is one that parks `Mesh._open`, so anything that secretly
33
+ needs the mesh hangs instead of passing slowly.
34
+ 3. **Prove the test catches it** by reverting the fix. A test that passes both
35
+ before and after is worthless.
36
+ 4. **Verify on device again**, same package, same load.
37
+
38
+ ## Tools
39
+
40
+ From the repo root:
41
+
42
+ ```bash
43
+ bun run mesh-peer # the peer alone, stdin-driven
44
+ bun run mesh-lab <scenario> # peer + phone, orchestrated
45
+ ```
46
+
47
+ `examples/mesh-peer.mjs` — runs under `bare`. Prints `STORAGE`, `DEVICE`,
48
+ `INVITE`, then `READY`. Commands, one per line, answered on stdout:
49
+
50
+ | command | answer | notes |
51
+ | ------------------------------- | ---------------------------------- | ------------------------------------------------------------ |
52
+ | `invite` | `INVITE qvac://mesh/…` | this peer's mesh |
53
+ | `devices` | `DEVICES aabbccdd,…` | 8-char device id prefixes |
54
+ | `join <invite>` | `JOINED` | switch onto the phone's mesh |
55
+ | `chats` | `CHATS <n>` | what this peer can see |
56
+ | `seed [chats] [chunks] [title]` | `SEED i/n` … `SEEDED` | grows the oplog |
57
+ | `state` | `STATE members=… devices=… live=…` | one parseable line of membership |
58
+ | `members` / `rows` / `activity` | listings | membership is mesh-internal; no RPC carries it |
59
+ | `ourmember` | `OURMEMBER aabbccdd` | this peer's member id |
60
+ | `align` | `ALIGN flushes=…` | `host.clock`, the number the phone's debug panel shows |
61
+ | `ff` | `FF <n>` | gaps crossed by adopting a head instead of replaying into it |
62
+ | `len <deviceprefix>` | `LEN <n>` | a writer's oplog length |
63
+ | `kick <deviceprefix>` | `KICKED aabbccdd` | revoke on demand |
64
+ | `write [title]` | `WROTE <chatId>` | one cheap op |
65
+ | `quit` | — | closes cleanly |
66
+
67
+ Commands are serialised, so a piped script is safe.
68
+
69
+ `examples/device.mjs` — the platform-neutral surface: `ensureTarget`, `launch`,
70
+ `stop`, `deepLink`, `installed`, `resetApp`, `clearLogs`, `logs`, `timeBoot`,
71
+ `timeBootUntil`, `launchTiming`, `bootTrace`, `bootReport`, `bootPhase`,
72
+ `screenshot`, `typeText`, `swipe`, `setAirplaneMode` (Android only), plus UI
73
+ driving (`nodes`, `ids`, `strings`, `find`, `waitFor`, `tap`, `tapUntil`,
74
+ `tapIfPresent`, `tapNode`, and `byId`/`byText`/`byTextStart`/`byExactText`). It
75
+ picks a backend and nothing above it is platform-aware.
76
+
77
+ `examples/device-adb.mjs` / `examples/device-idb.mjs` — the backends. Both
78
+ return the same normalized node: `{ id, strings, bounds: [x1,y1,x2,y2], raw }`.
79
+ `id` is the `testID` either way (`resource-id` on Android, `AXUniqueId` on iOS),
80
+ and `strings` collects every textual value on the node (`text` +
81
+ `content-desc`; `AXLabel` + `AXValue` + `title`) so one matcher works on both.
82
+
83
+ `examples/boot-report-parse.mjs` — `parseBootReport`, `filterBootLines` and
84
+ `checkBootConcurrency`, kept separate from the backends so the boot assertions
85
+ are unit-testable without a device.
86
+
87
+ `examples/mesh-lab.mjs` — scenarios: `pair`, `grow`, `boot-timing`, `converge`,
88
+ `chaos` (membership under kill/reboot/kick/interrupted-rejoin), `trio` (the
89
+ phone owns the member and two peers join at once), `partition` (airplane mode
90
+ under a running app). `chaos` onboards a fresh install itself (Get Started →
91
+ name → "Run QVAC on this device" → model → shell; nothing waits on the download),
92
+ and pairs in whichever direction the platform allows: Android takes the invite as
93
+ a deep link, iOS has the peer join the phone's mesh, so there the phone owns the
94
+ member and its own pass attests the peer.
95
+
96
+ Env: `QVAC_TARGET`, `QVAC_PKG`, `MESH_STORAGE`, `MESH_CHATS`, `MESH_CHUNKS`,
97
+ `MESH_TITLE`, `MESH_DEVICE`, `MESH_INVITE`, `QVAC_LOG_WINDOW`; iOS also takes
98
+ `QVAC_SIM` (device name, default `qvac-mesh-lab`) and `QVAC_SIM_DEVICE` (e.g.
99
+ `iPhone-17-Pro`).
100
+
101
+ ```bash
102
+ QVAC_TARGET=ios QVAC_PKG=io.tether.qvac bun run mesh-lab boot-timing
103
+ ```
104
+
105
+ The app id is the same string on both platforms (`io.tether.qvac`,
106
+ `.development`, `.staging`).
107
+
108
+ `MESH_STORAGE` defaults to a stable path so the peer keeps its identity across
109
+ runs. Only set it to run two independent peers, and do not hand-write the
110
+ default — `os.tmpdir()` is not `/tmp` on macOS, so a guessed path mints a _new_
111
+ mesh and the phone is no longer on it. `mesh-lab` refuses to run a scenario
112
+ against a mesh the phone has not joined; run `pair` deliberately.
113
+
114
+ Pairing a phone onto successive throwaway meshes leaves it a writer in a mesh
115
+ with no surviving peers, and its autobee dies with `No local nodes` — the app
116
+ then shows "Core v2 mesh reported an error". Recover with
117
+ `adb shell pm clear <pkg>` and pair once.
118
+
119
+ ## Producing "the phone is behind"
120
+
121
+ This is the state most mesh bugs need, and the order matters:
122
+
123
+ ```bash
124
+ QVAC_PKG=io.tether.qvac MESH_CHATS=15 MESH_CHUNKS=40 bun run mesh-lab boot-timing
125
+ ```
126
+
127
+ Pair → kill the phone → grow the mesh while it is gone → relaunch and time it.
128
+ Growing _before_ the kill just replicates normally and reproduces nothing.
129
+
130
+ ## Boot timing
131
+
132
+ Measure the tight window, not wall-clock. The app prints its whole boot timeline
133
+ as one `[BOOT]` block when the splash hides, and `bootReport()` parses it into
134
+ `{ phases, note, totalMs, unmeasured, late }`; `bootPhase('harness', 'entry')`
135
+ picks one out. `bootTrace()` still returns the raw lines.
136
+
137
+ Both worklets forward their marks to the host over the ipc they already hold, so
138
+ the whole timeline is one `console.log` that cannot interleave with the two
139
+ worklets logging concurrently. **`grep ':boot]'` finds the block's boundaries —
140
+ its header, its `BOOT total:` and any `BOOT late:` line — and nothing else;** the
141
+ phase lines, `[DEVICE]` and `note:` carry no tag, so `bootReport()` is what reads
142
+ the interior. Separately the app's own splash, error boundary and fresh-install
143
+ guard print bare `[boot]` _failure_ messages with no timings, and on a wedged
144
+ boot those are the only lines there are — `bootTrace()` matches them, so use it
145
+ before concluding the app printed nothing.
146
+
147
+ `mesh-lab boot-timing` asserts the concurrency, not just a wall-clock number:
148
+ `checkBootConcurrency(report)` requires the two `worklet boot` marks to start
149
+ within 200ms of each other and no harness phase to land after the gate, and it
150
+ throws when a hard check fails. Both launch marks are stamped where the work
151
+ happens, so moving the prestart below the assistant worklet's start drifts them
152
+ apart rather than leaving a green assertion behind. Do **not** assert that the
153
+ harness reaches a later phase before the assistant does: the assistant
154
+ legitimately wins that race once its own graph shrinks, which is why the ready
155
+ margin is soft.
156
+
157
+ Phases are concurrent, so read `startOffset` rather than summing durations. A
158
+ component still running when the gate closed renders `(open)`; a phase that
159
+ lands after the gate gets its own `BOOT late:` line, which is exactly how a
160
+ deferred child creeping back onto the critical path shows up.
161
+
162
+ `totalMs` starts at the first JS the app can reach, so it excludes the native
163
+ process start and RN init that `unmeasured` names — around 650–850ms on a Pixel
164
+ 6 Pro. Never quote it against `launchTiming` or an `am start` figure.
165
+
166
+ ## A fast splash proves nothing on its own
167
+
168
+ If the fix defers work, show the work still lands — otherwise "fast" may mean
169
+ "never saw the mesh". `mesh-lab converge` seeds a titled batch and then asserts
170
+ those chats render on the phone. Use a distinctive `MESH_TITLE`.
171
+
172
+ ## Reading the boot chain
173
+
174
+ Mobile blocks its splash on the whole worklet tree, so anything slow inside it
175
+ _is_ splash time:
176
+
177
+ ```
178
+ splash ← the app's root boot ← await ipc.ready
179
+ ← stowEntry ready() ← await sup.ready() (bare-supervisor/entry)
180
+ ← Supervisor._boot() starts children SERIALLY: core → engine → harness → assistant
181
+ ← QvacAssistant._open()
182
+ ```
183
+
184
+ `await ipc.ready` happens _before_ the app's store is built, so a slow child is
185
+ not "slow after load" — it is a blank screen.
186
+
187
+ Corollary worth internalising: **`mesh.dispatch()` awaits a full mesh drain.**
188
+ `autobee.append()` returns `_bump()`, the shared drain promise, and `update()`
189
+ is the same call. So any mesh write on a boot path waits out replication. The
190
+ write itself is a RAM enqueue; durability comes from `flushLocal` inside the
191
+ drain.
192
+
193
+ ## Getting your Core change onto the phone
194
+
195
+ The app builds from `tetherto/qvac-app`; these are its traps, and they are how a
196
+ Core change silently fails to ship.
197
+
198
+ - **Verify the APK carries your change.** `expo run:android --variant release`
199
+ reuses a cached JS bundle. Delete
200
+ `android/app/build/generated/assets/react/release` and
201
+ `android/app/build/intermediates/assets/release` first, then confirm:
202
+ `unzip -p <apk> res/<x>.bundle | grep <your-symbol>`. The bundles are
203
+ resource-renamed inside the APK (`res/Ie.bundle`), so match them by byte size
204
+ against the worklet build output.
205
+ - **`mobile:android` does not rebuild the worklets.** Only `mobile:prebuild`
206
+ runs `build:all`. Gradle rebundles the RN JS, so an app-side change appears
207
+ while a Core change silently ships stale — the app runs the previous Core and
208
+ every symptom points at your code being wrong rather than absent. Run the
209
+ app repo's `rebuild:native` first for any Core change, and grep the bundle
210
+ before believing a result.
211
+ - **`.env.local` may set `EXPO_PUBLIC_QVAC_WORKLET_SMOKE`**, which boots a smoke
212
+ screen instead of the app. Build with `EXPO_NO_DOTENV=1`; do not edit the file.
213
+ - **`android/app/build.gradle` bakes `applicationId` at prebuild time**, so
214
+ `APP_VARIANT` at gradle time does not change the package. A release build of
215
+ the dev variant can still install as `io.tether.qvac`.
216
+
217
+ ## Device gotchas that cost real time
218
+
219
+ - **`adb install` can report `Success` and leave no launchable activity.** Check
220
+ `adb shell cmd package resolve-activity --brief -c
221
+ android.intent.category.LAUNCHER <pkg>`; uninstall + reinstall fixes it.
222
+ `mesh-lab` refuses to start in this state.
223
+ - **Deep-link pairing needs a matching scheme.** The invite is `qvac://mesh/…`;
224
+ the production variant registers `qvac` (works), the `development` variant
225
+ registers `qvac-dev` and `meshInviteFromUrl` rejects it. For a dev build, read
226
+ the invite off the phone (Settings → My Devices → Pair New Device → Show QR
227
+ Code) and `join` it from the peer instead.
228
+ - **A deep link pairs even during onboarding**, but does not complete
229
+ onboarding — the phone rejoins onboarding on the next launch and has no chat
230
+ shell, so UI assertions fail. Onboard first (name → "Run QVAC on this device"
231
+ → model download) when a scenario needs the chat list.
232
+ - **`uiautomator` taps get swallowed** by the RN drawer on first press; use
233
+ `tapUntil`, which retries until the next screen appears. A stray tap can land
234
+ you in Android Settings — assert on a `resource-id` before continuing.
235
+ - **The Electron desktop peer is the wrong tool.** The bare peer is lighter and
236
+ does not depend on a desktop build.
237
+ - Screenshots: `screenshot(path)` on either backend, then read the file. Cheaper
238
+ than a UI dump when you just need to see what is on screen.
239
+
240
+ ## iOS specifics
241
+
242
+ Verified working: provisioning a simulator from nothing, `installed`, `launch`,
243
+ `stop`, accessibility dump and normalisation, text matching, in-app `tap`,
244
+ `logs`, `screenshot`. These do **not** carry over from Android:
245
+
246
+ - **The invite deep link is blocked.** iOS gates a scheme handoff behind a
247
+ SpringBoard "Open in …?" alert. It is not the app's own UI, so `idb ui tap`
248
+ cannot press it and `simctl openurl` raises the same alert — only Appium's
249
+ alert API reaches it. `deepLink` throws with that explanation rather than
250
+ stranding the dialog. Pair the other way on iOS: read the invite off the app
251
+ and `join <invite>` from the peer, which needs the app past onboarding.
252
+ - **`testID` does not surface.** RN maps it to the accessibility identifier, but
253
+ `AXUniqueId` came back empty for every app node in a Release build, so `byId`
254
+ finds nothing. Drive iOS with `byText` / `byTextStart` / `byExactText`.
255
+ - **Core's logs do surface, in the system log.** `simctl spawn <udid> log show
256
+ --last 15m --info` carries the `(BareKit) [qvac-app-core:…]` lines, contract
257
+ ops included — which is what `device.logs()` reads. They are absent from the
258
+ `expo run:ios` console, which only carries the host's forwarded `[BOOT]`
259
+ marks, so a `grep contract` there returns nothing and reads as "iOS does not
260
+ log". Verified on a Debug simulator build.
261
+ - **A camera-less device cannot join a mesh at all.** "Pair to another device"
262
+ goes straight to a QR scanner with no manual-entry or paste path, so a
263
+ simulator can never join an existing mesh. Give it "Run QVAC on this device",
264
+ then read its own invite and `join` that from the peers — the simulator owns
265
+ the mesh and everything else joins it.
266
+ - **The invite is plain text**, beside the QR under "or share an invite link"
267
+ (Settings → My Devices → Pair New Device → Show QR Code). No decoding needed,
268
+ on either platform, which is what makes phone-owns-the-mesh scriptable.
269
+ - **A simulator dev-client build needs Metro** and stops on its launcher until
270
+ told which bundle to load. `device-idb.launch` handles it: the app's _own_
271
+ scheme raises no SpringBoard alert, so
272
+ `simctl openurl 'exp+qvac-mobile://expo-development-client/?url=…'` skips the
273
+ launcher; the developer-menu primer's Continue then opens the full menu, which
274
+ needs its own Close, and `dumpNodes` clears either whenever it sees one.
275
+ `expo run:ios` never exits on its own after "Opening on …" — it tails the log —
276
+ so a scripted build kills it. The route form `…/--/settings/my-devices` does
277
+ **not** load ("Failed to open app").
278
+ - **The simulator keychain survives an uninstall**, so a "fresh install" keeps
279
+ debug mode and the old recovery phrase, and the debug bar then sits over the
280
+ header. `xcrun simctl keychain <udid> reset` before reinstalling is what makes
281
+ it fresh. The drawer is opened with an edge swipe on iOS, because the debug bar
282
+ and the dev-client gear both cover its button.
283
+ - **The simulator's swarm shows `Conns 0`.** Join, attestation and the wakeup
284
+ fast-forward still arrive, but a kick issued by the lab peer never reached the
285
+ simulator in two 90s windows and a further 100s with the peer held open — the
286
+ lab peer configures no blind peers, so with no direct connection there is no
287
+ path. `chaos` therefore stops being meaningful at the kick on iOS; the same
288
+ step passes on the Pixel. Treat the simulator as a join/fast-forward target,
289
+ not a revocation one, until the lab peer is given a blind peer.
290
+ - **Addressing nodes on iOS is by label** (`NODES` in `mesh-lab`: `Open chats`,
291
+ `Settings`, `My Devices`, `Pair New Device`, `Debug`, `Recovery phrase`, `✕`),
292
+ and a row folds its values into the label after a comma, so match the lead.
293
+ - **Debug mode is unlocked by ten taps on the Settings title** within 1.5s each.
294
+ On a fresh install neither the Debug row nor the stats panel exists until you
295
+ do it, and the scenarios that read either have to establish it first.
296
+ - **iOS collapses a row into one accessibility label**, values included, so
297
+ `byExactText('Recovery phrase')` misses and the phrase arrives inside the
298
+ row's own label. Use `byTextStart` and read the value out of that string.
299
+ - **The Expo dev-client menu intercepts taps** on a Debug simulator build, often
300
+ right after a relaunch. Dismiss "Close"/"Continue" before asserting, or a
301
+ healthy app reads as a wedged one.
302
+ - **No log marker has ever been seen on an iOS Release build.** `timeBoot`
303
+ returned null there, so use `timeBootUntil`, which measures launch until a UI
304
+ node appears — platform-neutral, and the metric a user actually sees. This may
305
+ be a tooling bug rather than a routing one: `log show` omits info-level entries
306
+ unless asked, and every line the app emits is info. `device-idb.mjs` now passes
307
+ `--info`. That cannot be validated here: `device-idb.mjs` is `simctl spawn`
308
+ throughout, a **simulator-only** path that never reads a physical device, so
309
+ the whole iOS side of `[BOOT]` is unverified against real hardware.
310
+ - **`idb` is not on PATH.** It installs via pip as `fb-idb`, landing in
311
+ `~/Library/Python/3.9/bin/idb`, with `idb_companion` from brew.
312
+ `device-idb.mjs` resolves that path itself; override with `IDB_BIN`. Do not
313
+ conclude it is missing because `command -v idb` is empty.
314
+ - **The system log cannot be truncated**, so `clearLogs()` records a timestamp
315
+ and `logs()` runs `simctl spawn <udid> log show --start <mark>`. On a real
316
+ device that path does not apply — the simulator is what this backend targets.
317
+ - **A simulator boots before its springboard is ready**; the first
318
+ `ui describe-all` returns one all-zero element. `waitFor` handles it; a bare
319
+ `nodes()` immediately after boot will look empty.
320
+ - iOS needs a simulator build of the app before `launch` and the invite deep
321
+ link have anything to target. `installed()` fails fast when the app is absent.
322
+
323
+ ## Placement
324
+
325
+ Device and mesh repro drivers live in `examples/` and run under `bare`. Their
326
+ regression tests go in `test/`. Appium-based end-to-end coverage is a different
327
+ stack in `tetherto/qvac-app`; this one deliberately is not that, so do not grow
328
+ it in that direction.