@qvac/core 0.3.0 → 0.3.1
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.
- package/dist-lib/lib/api/chat.d.ts +3 -1
- package/dist-lib/lib/api/chat.js +6 -2
- package/dist-lib/lib/api/index.d.ts +2 -0
- package/dist-lib/lib/api/index.js +3 -1
- package/dist-lib/lib/api/inference-calls.d.ts +18 -0
- package/dist-lib/lib/api/inference-calls.js +15 -0
- package/dist-lib/lib/api/rag.js +10 -2
- package/dist-lib/lib/assistant/harness.d.ts +1 -0
- package/dist-lib/lib/assistant-tree.d.ts +2 -0
- package/dist-lib/lib/assistant-tree.js +11 -2
- package/dist-lib/lib/assistant.d.ts +14 -1
- package/dist-lib/lib/assistant.js +107 -15
- package/dist-lib/lib/core/chunk.js +5 -0
- package/dist-lib/lib/core/files/rag/build.d.ts +1 -2
- package/dist-lib/lib/core/files/rag/build.js +1 -2
- package/dist-lib/lib/core/files/rag/extract/office-collabora.d.ts +1 -1
- package/dist-lib/lib/core/files/rag/index.d.ts +4 -24
- package/dist-lib/lib/core/files/rag/index.js +3 -17
- package/dist-lib/lib/core/files/rag/load.d.ts +1 -2
- package/dist-lib/lib/core/files/rag/load.js +1 -2
- package/dist-lib/lib/core/files/rag/produce.d.ts +1 -1
- package/dist-lib/lib/core/files/rag/produce.js +1 -3
- package/dist-lib/lib/core/files/rag/retrieval/full-text.d.ts +1 -1
- package/dist-lib/lib/core/files/rag/retrieval/full-text.js +1 -4
- package/dist-lib/lib/core/files/rag/similarity.d.ts +5 -0
- package/dist-lib/lib/core/files/rag/similarity.js +6 -0
- package/dist-lib/lib/core/files/upload.d.ts +1 -1
- package/dist-lib/lib/core/inference-calls-handoff.d.ts +20 -0
- package/dist-lib/lib/core/inference-calls-handoff.js +37 -0
- package/dist-lib/lib/core/inference-calls-receiver.d.ts +14 -0
- package/dist-lib/lib/core/inference-calls-receiver.js +39 -0
- package/dist-lib/lib/core/notification.js +5 -4
- package/dist-lib/lib/core.d.ts +8 -1
- package/dist-lib/lib/core.js +78 -4
- package/dist-lib/lib/inference-calls.d.ts +40 -0
- package/dist-lib/lib/inference-calls.js +266 -0
- package/dist-lib/schema/content.js +5 -1
- package/dist-lib/schema/engine.js +42 -1
- package/dist-lib/schema/qvac.js +4 -2
- package/dist-lib/spec/bind.js +3 -0
- package/dist-lib/spec/calls.js +1 -0
- package/dist-lib/spec/capabilities.d.ts +2 -0
- package/dist-lib/spec/hrpc/hrpc.json +13 -0
- package/dist-lib/spec/hrpc/index.js +15 -3
- package/dist-lib/spec/hrpc/messages.js +172 -49
- package/dist-lib/spec/hyperschema/index.js +172 -49
- package/dist-lib/spec/hyperschema/schema.json +127 -1
- package/dist-lib/spec/hyperschema/types.d.ts +34 -1
- package/dist-lib/spec/local/hyperdb/messages.js +64 -128
- package/dist-lib/spec/local/hyperschema/index.js +32 -64
- package/dist-lib/spec/local/hyperschema/schema.json +16 -0
- package/dist-lib/spec/mesh/hyperdb/messages.js +176 -311
- package/dist-lib/spec/mesh/hyperdispatch/messages.js +132 -236
- package/dist-lib/spec/mesh/hyperschema/index.js +132 -236
- package/dist-lib/spec/mesh/hyperschema/schema.json +70 -1
- package/dist-lib/spec/mesh/hyperschema/types.d.ts +3 -1
- package/package.json +14 -17
- package/tui/lib/knowledge-import.mjs +1 -1
- package/.claude/skills/asana/SKILL.md +0 -86
- package/.claude/skills/compaction/SKILL.md +0 -136
- package/.claude/skills/device-mesh-debug/SKILL.md +0 -328
- package/.claude/skills/gh-stack/SKILL.md +0 -181
- package/.claude/skills/gh-stack/references/commands.md +0 -177
- package/.claude/skills/gh-stack/references/stack-design.md +0 -97
- package/.claude/skills/gh-stack/references/troubleshooting.md +0 -159
- package/.claude/skills/js-house-style/SKILL.md +0 -671
- package/.claude/skills/pr-create/SKILL.md +0 -243
- package/.claude/skills/pr-review/SKILL.md +0 -428
- package/.claude/skills/release/SKILL.md +0 -122
- package/CLAUDE.md +0 -48
- package/dist-lib/lib/core/files/rag/artifact/codec.d.ts +0 -3
- package/dist-lib/lib/core/files/rag/artifact/codec.js +0 -172
- package/dist-lib/lib/core/files/rag/artifact/id.d.ts +0 -10
- package/dist-lib/lib/core/files/rag/artifact/id.js +0 -39
- package/dist-lib/lib/core/files/rag/artifact/types.d.ts +0 -24
- package/dist-lib/lib/core/files/rag/artifact/types.js +0 -41
- package/dist-lib/lib/core/files/rag/chunk/chunking.d.ts +0 -12
- package/dist-lib/lib/core/files/rag/chunk/chunking.js +0 -117
- package/dist-lib/lib/core/files/rag/chunk/metadata.d.ts +0 -30
- package/dist-lib/lib/core/files/rag/chunk/metadata.js +0 -89
- package/dist-lib/lib/core/files/rag/chunk/tokenizer.d.ts +0 -7
- package/dist-lib/lib/core/files/rag/chunk/tokenizer.js +0 -18
- package/dist-lib/lib/core/files/rag/extract/csv-text.d.ts +0 -1
- package/dist-lib/lib/core/files/rag/extract/csv-text.js +0 -117
- package/dist-lib/lib/core/files/rag/extract/document-types.d.ts +0 -22
- package/dist-lib/lib/core/files/rag/extract/document-types.js +0 -152
- package/dist-lib/lib/core/files/rag/extract/extract.d.ts +0 -17
- package/dist-lib/lib/core/files/rag/extract/extract.js +0 -81
- package/dist-lib/lib/core/files/rag/extract/html-table-text.d.ts +0 -1
- package/dist-lib/lib/core/files/rag/extract/html-table-text.js +0 -125
- package/dist-lib/lib/core/files/rag/extract/html-text.d.ts +0 -1
- package/dist-lib/lib/core/files/rag/extract/html-text.js +0 -132
- package/dist-lib/lib/core/files/rag/extract/pdf-platform.d.ts +0 -17
- package/dist-lib/lib/core/files/rag/extract/pdf-platform.js +0 -141
- package/dist-lib/lib/core/files/rag/extract/pdf-text.d.ts +0 -12
- package/dist-lib/lib/core/files/rag/extract/pdf-text.js +0 -43
- package/dist-lib/lib/core/files/rag/extract/rtf-text.d.ts +0 -1
- package/dist-lib/lib/core/files/rag/extract/rtf-text.js +0 -15
- package/dist-lib/lib/core/files/rag/extract/text-decoding.d.ts +0 -1
- package/dist-lib/lib/core/files/rag/extract/text-decoding.js +0 -91
- package/dist-lib/lib/core/files/rag/extract/types.d.ts +0 -36
- package/dist-lib/lib/core/files/rag/extract/types.js +0 -12
- package/dist-lib/lib/core/files/rag/extract/utf.d.ts +0 -2
- package/dist-lib/lib/core/files/rag/extract/utf.js +0 -18
- package/dist-lib/lib/core/files/rag/retrieval/citation-match.d.ts +0 -2
- package/dist-lib/lib/core/files/rag/retrieval/citation-match.js +0 -16
- package/dist-lib/lib/core/files/rag/retrieval/coverage.d.ts +0 -4
- package/dist-lib/lib/core/files/rag/retrieval/coverage.js +0 -48
- package/dist-lib/lib/core/files/rag/retrieval/diversity.d.ts +0 -10
- package/dist-lib/lib/core/files/rag/retrieval/diversity.js +0 -37
- package/dist-lib/lib/core/files/rag/retrieval/floor.d.ts +0 -5
- package/dist-lib/lib/core/files/rag/retrieval/floor.js +0 -21
- package/dist-lib/lib/core/files/rag/retrieval/format.d.ts +0 -6
- package/dist-lib/lib/core/files/rag/retrieval/format.js +0 -21
- package/dist-lib/lib/core/files/rag/retrieval/knowledge.d.ts +0 -2
- package/dist-lib/lib/core/files/rag/retrieval/knowledge.js +0 -54
- package/dist-lib/lib/core/files/rag/retrieval/notices.d.ts +0 -16
- package/dist-lib/lib/core/files/rag/retrieval/notices.js +0 -27
- package/dist-lib/lib/core/files/rag/retrieval/scoring.d.ts +0 -8
- package/dist-lib/lib/core/files/rag/retrieval/scoring.js +0 -82
- package/dist-lib/lib/core/files/rag/retrieval/search.d.ts +0 -3
- package/dist-lib/lib/core/files/rag/retrieval/search.js +0 -49
- package/dist-lib/lib/core/files/rag/retrieval/selection.d.ts +0 -11
- package/dist-lib/lib/core/files/rag/retrieval/selection.js +0 -93
- package/dist-lib/lib/core/files/rag/retrieval/source-tag-filter.d.ts +0 -6
- package/dist-lib/lib/core/files/rag/retrieval/source-tag-filter.js +0 -79
- package/dist-lib/lib/core/files/rag/retrieval/sources.d.ts +0 -13
- package/dist-lib/lib/core/files/rag/retrieval/sources.js +0 -20
- package/dist-lib/lib/core/files/rag/retrieval/target.d.ts +0 -13
- package/dist-lib/lib/core/files/rag/retrieval/target.js +0 -89
- package/dist-lib/lib/core/files/rag/retrieval/terms.d.ts +0 -8
- package/dist-lib/lib/core/files/rag/retrieval/terms.js +0 -70
- package/dist-lib/lib/core/files/rag/retrieval/types.d.ts +0 -29
- package/dist-lib/lib/core/files/rag/retrieval/types.js +0 -1
- package/dist-lib/lib/core/files/rag/retrieval/web-sources.d.ts +0 -8
- package/dist-lib/lib/core/files/rag/retrieval/web-sources.js +0 -41
- package/dist-lib/lib/core/files/rag/retrieval/whole-document-query.d.ts +0 -1
- package/dist-lib/lib/core/files/rag/retrieval/whole-document-query.js +0 -96
- package/dist-lib/lib/core/files/rag/vector/memory.d.ts +0 -15
- package/dist-lib/lib/core/files/rag/vector/memory.js +0 -135
- package/dist-lib/lib/core/files/rag/vector/types.d.ts +0 -28
- package/dist-lib/lib/core/files/rag/vector/types.js +0 -1
|
@@ -1,86 +0,0 @@
|
|
|
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.
|
|
@@ -1,136 +0,0 @@
|
|
|
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, and
|
|
78
|
-
reactively once the harness overflow ladder is exhausted. Never at the end of a
|
|
79
|
-
run on its own numbers — that path existed and was removed (see the decision
|
|
80
|
-
record): the turn that fills the window ends cleanly, publishes its full reading,
|
|
81
|
-
and the next message folds first, keeping itself verbatim. The proactive share is
|
|
82
|
-
tiered by window — 75% under 12k, 82% under 16k, 85% under 32k, 90% under 64k,
|
|
83
|
-
95% from there — because the band has to hold a whole thinking turn and
|
|
84
|
-
`cacheTokens` reports a turn with its thinking stripped. Both folds announce a
|
|
85
|
-
`compacting` phase. The before-run fold announces before anything streamed and
|
|
86
|
-
clears the phase, because its run carries on; the overflow fold can land behind
|
|
87
|
-
a partial answer, since a mid-stream overflow is not retried, and its failed
|
|
88
|
-
status closes the phase. That announcement is not an attempt start in
|
|
89
|
-
`historyFromChunks` — reading it as one drops the streamed answer from every
|
|
90
|
-
later prompt — and clients exempt it from their restart rule for the same
|
|
91
|
-
reason.
|
|
92
|
-
|
|
93
|
-
After the fact the fold is visible from its chunk (`thread.compactionMarkers`,
|
|
94
|
-
anchored before the user message the fold precedes). Only the device that ran the
|
|
95
|
-
turn is a valid reading: `ctxSize` is per-device, so a chat that moved from a
|
|
96
|
-
phone carries a window this host does not have.
|
|
97
|
-
|
|
98
|
-
## Invalidation — when the chat key must die
|
|
99
|
-
|
|
100
|
-
[`lib/kv-cache-reclaim.ts`](../../../lib/kv-cache-reclaim.ts) owns the keys:
|
|
101
|
-
`chatKvCacheKey(chatId)` and `chatRepairKvCacheKey(chatId, acceptedRepairs)` — a
|
|
102
|
-
repair generation nests under the chat key, so deleting the chat key reclaims
|
|
103
|
-
every generation.
|
|
104
|
-
|
|
105
|
-
This repo deletes a chat's cache at three moments, and **a new feature that
|
|
106
|
-
changes history in place must route through the same invalidation**:
|
|
107
|
-
|
|
108
|
-
1. Before executing a superseding run — retry or regenerate, the `parentId`
|
|
109
|
-
run-request.
|
|
110
|
-
2. When a chat disappears from the chat list (`disappearedChatIds`).
|
|
111
|
-
3. For an agent's chats when its re-key fields change — bio, model, ctx,
|
|
112
|
-
kv-quant, tool and skill selection (`agentRekeyFingerprint`).
|
|
113
|
-
|
|
114
|
-
A future edit-message or delete-message feature is exactly case 1 in disguise.
|
|
115
|
-
Editing text that is already in the KV without dropping the key leaves the model
|
|
116
|
-
answering the _old_ text, invisibly.
|
|
117
|
-
|
|
118
|
-
Apps delete device-locally through the engine API: `clearKvCache()` and
|
|
119
|
-
`deleteChatKvCache({ id })` in [`lib/api/`](../../../lib/api/). Neither
|
|
120
|
-
replicates — the chat's warm cache may live on the provider device.
|
|
121
|
-
|
|
122
|
-
## Symptoms, and where they actually come from
|
|
123
|
-
|
|
124
|
-
| Symptom | Look here first |
|
|
125
|
-
| --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
126
|
-
| "the model forgot the middle of the chat" | something evicted history without invalidating — never the cache doing its job |
|
|
127
|
-
| "it answers the question I asked an hour ago" | a stale cache key that should have been deleted (retry/regenerate, agent re-key) |
|
|
128
|
-
| every turn is slow to first token | `configHash` churn — a volatile system prompt or a changing tool set re-keys the file each turn |
|
|
129
|
-
| a long chat errors instead of folding | `ctxSize` below `COMPACTION_MIN_CTX_SIZE`; the fold is refused by design |
|
|
130
|
-
| the summary is longer than what it replaced | `foldReducesPrompt` refused it — that is the guard working |
|
|
131
|
-
|
|
132
|
-
## Sibling skills
|
|
133
|
-
|
|
134
|
-
- The cache, the context window and the overflow ladder → **kvcache**, in
|
|
135
|
-
`@qvac/harness`.
|
|
136
|
-
- How the code itself should be shaped → **js-house-style**.
|
|
@@ -1,328 +0,0 @@
|
|
|
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.
|