@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,180 @@
1
+ ---
2
+ name: pr-create
3
+ description: Write the title, body and commits for a pull request in @qvac/core, and decide the conventional-commit type for a change — `fix` is reserved for user-facing defects in a released version. Use when opening a PR here, splitting work into a stack, or choosing between `fix` and `chore`.
4
+ ---
5
+
6
+ # PR creation
7
+
8
+ `@qvac/core` is a published package. The log is the only durable record of intent,
9
+ and for this repo it is also the changelog a consumer reads before upgrading.
10
+
11
+ ## Title
12
+
13
+ ```
14
+ type(scope): subject
15
+ ```
16
+
17
+ Imperative, lowercase after the colon, no trailing period. Scope optional, and
18
+ only when it narrows something real. What and why, not how.
19
+
20
+ ```
21
+ feat: publish the sidecar entry, so spawning it needs no bundle
22
+ fix(publish): repoint dynamic imports at dist-lib too
23
+ refactor: own the schema codegen tooling
24
+ chore: regenerate the schema
25
+ ```
26
+
27
+ There is no ticket prefix here, and no title validator in CI. That is not
28
+ licence to be loose: nothing will catch a bad title but a reviewer.
29
+
30
+ ## Types
31
+
32
+ ```
33
+ build chore ci docs style refactor perf test fix feat
34
+ ```
35
+
36
+ **`fix` is reserved for a defect a consumer of a released version could hit.**
37
+ It is the line someone reads to decide whether to upgrade, so it claims real
38
+ breakage in something already published.
39
+
40
+ | The change | Type |
41
+ | ----------------------------------------------------------- | -------------------------------------------------- |
42
+ | Breaks a consumer on a published version | `fix` |
43
+ | Repairs code that has never shipped (same release cycle) | `chore` |
44
+ | Repairs the build, the bundle, or what lands in the tarball | `build` or `fix` if a published artifact was wrong |
45
+ | Repairs CI, a workflow, an action pin | `ci` |
46
+ | Repairs or adds a test | `test` |
47
+ | Repairs a lint/type error | `chore` |
48
+ | Pure move or rename, no behaviour change | `refactor` |
49
+ | New capability, new export, new flag | `feat` |
50
+ | README, comments, docs | `docs` |
51
+
52
+ When a repair is on unreleased code, check the last release tag: if the bug was
53
+ never in a published version, it is `chore`, not `fix`.
54
+
55
+ Never relabel a real defect as `chore` to make the log quieter, and never
56
+ inflate a cleanup into `fix` to make it look urgent.
57
+
58
+ ## Scopes
59
+
60
+ Optional, and taken from what the diff actually touches — `lib`, `tui`, `schema`, `spec`, `scripts`, `test`, `ci`, `publish`, or a domain name (`mesh`, `sync`, `assistant`, `storage`).
61
+ A scope that restates the type (`fix(fix)`) or names the whole repo adds
62
+ nothing; leave it off.
63
+
64
+ ## Decision records
65
+
66
+ `docs/decisions/` holds the durable, non-obvious choices — why a boundary is
67
+ where it is, why an approach was rejected. They are reference for a future
68
+ reader, **not rules, and not to be loaded by default**.
69
+
70
+ Add one when this PR settles something a later reader would otherwise have to
71
+ reverse-engineer from the diff: a runtime or storage boundary, a wire-format or
72
+ schema choice, a build or publish constraint, a rejected alternative that will
73
+ look obvious later. Do not add one for a bug fix, a rename, or anything the code
74
+ already says plainly.
75
+
76
+ Copy `docs/decisions/TEMPLATE.md`, give it a `status`, list it once in
77
+ `INDEX.md`, and name it in the PR's Decisions section. `node
78
+ scripts/docs-audit.cjs` checks all of that, and CI runs it.
79
+
80
+ An **active** record may cite only paths that exist here; a path in another
81
+ repository is written `@qvac/harness → lib/x.ts` so the audit treats it as
82
+ context rather than a local file. A superseded record is exempt — it describes
83
+ how things used to be.
84
+
85
+ ### One PR, one type
86
+
87
+ The commits carry conventional-commit types, so the mix of types _is_ the scope
88
+ statement. `feat:`, `fix:` and `chore:` on one branch is not a well-rounded
89
+ change, it is three changes sharing a branch, and a reviewer has to hold all
90
+ three while judging any one of them.
91
+
92
+ List them before writing the body:
93
+
94
+ ```bash
95
+ git log --format='%s' main..HEAD | grep -oE '^[a-z]+' | sort -u
96
+ ```
97
+
98
+ - **One type** is the PR's type.
99
+ - **A dominant type plus its own tests or docs** (`feat` + `test`, `fix` +
100
+ `docs`) is fine; the dominant one wins.
101
+ - **Unrelated types** means split the PR, or stack it.
102
+
103
+ ## Small PRs, stacked
104
+
105
+ A PR is read by a human, so it has to fit in one head. Default to one concern.
106
+ When a change decomposes into dependent steps, do not grow one PR to fit them —
107
+ stack them, so each step is reviewable alone and lands in order.
108
+
109
+ - A large refactor belongs on a `refactor/...` branch with `refactor:` commits.
110
+ - **Refactor commits never live inside a non-refactor branch.** A `feat/` branch
111
+ that also reshuffles unrelated code is two PRs. Behaviour changes and pure
112
+ moves are reviewed differently, and mixing them hides both.
113
+ - A pure rename or move lands _before_ the change that depends on it, as its own
114
+ commit or its own PR in the stack.
115
+
116
+ Branch names must never contain `codex`, `cursor`, or `claude` (case
117
+ insensitive). Use a neutral name before committing or pushing.
118
+
119
+ ## Body
120
+
121
+ `.github/pull_request_template.md` pre-fills the headings. Keep its shape, fill
122
+ what applies, and delete the sections that would be empty — an absent section
123
+ says more than one saying "n/a". The template's own order is Why, What, Testing,
124
+ Decisions; the expanded form below is what each should contain.
125
+
126
+ ```markdown
127
+ ## What
128
+
129
+ One paragraph. The change, in the reviewer's terms.
130
+
131
+ ## Why
132
+
133
+ The problem this solves, or the decision it implements. Link the issue,
134
+ PR, or upstream change that forced it.
135
+
136
+ ## How
137
+
138
+ Only the parts a reader would not infer from the diff: the seam that moved,
139
+ the invariant being preserved, the thing that looks wrong but isn't.
140
+
141
+ ## Testing
142
+
143
+ What you ran, and what it proved. ``bun run test` (node, bare and addon lanes)` at minimum.
144
+ Say plainly when something could not be tested locally and why.
145
+ ```
146
+
147
+ For a **breaking change**, say so in the body under its own `## Breaking`
148
+ heading, with the migration a consumer has to perform. Published package —
149
+ this is the only warning they get.
150
+
151
+ ## Before opening
152
+
153
+ 1. Check the branch is not `main` and the name is neutral.
154
+ 2. `git log --oneline main..HEAD` — every commit is a conventional commit, and
155
+ each one is a change you would defend on its own. A trail of `wip`,
156
+ `fixup` or `address review` commits is not history; reshape it before
157
+ opening.
158
+ 3. `bun run lint` and ``bun run test` (node, bare and addon lanes)` pass locally. CI runs the same lanes; a
159
+ red PR wastes a reviewer's round trip.
160
+ 4. Rebase on `main` rather than merging it in. A merge commit in the branch
161
+ makes the diff unreadable.
162
+ 5. Open as a **draft** unless you are asking for review right now.
163
+
164
+ ```bash
165
+ gh pr create --repo tetherto/qvac-core --draft --title "type(scope): subject" --body-file <path>
166
+ ```
167
+
168
+ Never push to `main`, never force-push a branch someone else is reviewing, and
169
+ never open a PR that carries commits you did not write without saying so.
170
+
171
+ ## Version bumps
172
+
173
+ Release PRs in this repo are titled by version alone (`0.2.4 (#32)`,
174
+ `release/0.1.4 (#40)`). They carry the version bump and nothing else — do not
175
+ fold a bump into a feature PR, and do not fold a feature into a bump.
176
+
177
+ ## Sibling skills
178
+
179
+ - Reviewing a PR or a local diff → **pr-review**.
180
+ - How the code itself should be shaped → **js-house-style**.
@@ -0,0 +1,216 @@
1
+ ---
2
+ name: pr-review
3
+ description: Deep-dive review of a pull request in @qvac/core, or of local uncommitted/branch changes when invoked with `local`. Checks CI, the commit type and title, code quality against the house style, contract and API mismatches, and missing tests. In PR mode it creates PENDING inline comments only after the user confirms them, and never submits the review event. In local mode it prints findings in chat and posts nothing. Use when reviewing a PR, given a PR link, or asked to review the working tree or current branch.
4
+ ---
5
+
6
+ # PR review
7
+
8
+ Reviews changes in `@qvac/core`. Two modes.
9
+
10
+ - **PR mode** (a PR number or URL) — a short overview in chat, then a **pending**
11
+ GitHub review of per-file inline comments. The pending review is created only
12
+ after the user confirms the exact set of comments. **Never submit the review
13
+ event** (`COMMENT`, `REQUEST_CHANGES`, `APPROVE`) — that is the user's call,
14
+ from the GitHub UI.
15
+ - **Local mode** (`local`, or "review my changes") — the overview in chat only.
16
+ Posts nothing, anywhere.
17
+
18
+ ## Reviewing is read-only
19
+
20
+ This skill never writes to the working tree. Against the user's repo these are
21
+ forbidden, whatever the reason:
22
+
23
+ - `git switch`, `git checkout`, `git reset`, `git restore`, `git clean`
24
+ - `git stash`, in any form
25
+ - `git pull`, `git merge`, `git rebase`, `git cherry-pick`
26
+ - `gh pr checkout`
27
+ - any edit to a file
28
+
29
+ Local mode reads the diff with `git diff`, `git status` and `git ls-files`, and
30
+ nothing else. If the tree is dirty in a way that makes the diff hard to read, say
31
+ so and let the user decide; never tidy it yourself. A review that loses
32
+ uncommitted work is worse than no review.
33
+
34
+ PR mode needs no checkout at all: `gh pr diff` gives the patch, and
35
+ `gh api repos/{owner}/{repo}/contents/{path}?ref={sha}` gives any file at the PR
36
+ head.
37
+
38
+ ## Gather
39
+
40
+ PR mode:
41
+
42
+ ```bash
43
+ gh pr view <num> --repo tetherto/qvac-core \
44
+ --json title,body,author,headRefName,headRefOid,baseRefName,files,additions,deletions,state,isDraft,mergeable
45
+ gh pr diff <num> --repo tetherto/qvac-core --patch > /tmp/pr-<num>.patch
46
+ ```
47
+
48
+ Read the patch from the file with Read/Grep rather than re-running `gh` — it is
49
+ the same bytes every time and the file is greppable.
50
+
51
+ Local mode:
52
+
53
+ ```bash
54
+ git diff --staged > /tmp/local-staged.patch
55
+ git diff > /tmp/local-unstaged.patch
56
+ git status --porcelain=v1
57
+ git ls-files --others --exclude-standard # untracked, easy to miss
58
+ ```
59
+
60
+ For a branch rather than a working tree: `git diff main...HEAD` (three dots —
61
+ the merge base, not the tip).
62
+
63
+ ## CI
64
+
65
+ One workflow gates this repo: **Integrate** (`.github/workflows/ci.yml`), a
66
+ single `Lint & Tests` job. `publish.yml` runs on release, not on PRs.
67
+
68
+ Its steps are each a separate way to fail, and the last three catch what a
69
+ local `bun run test` does not:
70
+
71
+ | Step | Command | Fails when |
72
+ | ------------------------ | ---------------------- | --------------------------------------------------------------------------------------------- |
73
+ | Lint | `bun run lint` | prettier, lunte or `tsc --noEmit` |
74
+ | Schema is regenerated | `bun run build:schema` | `spec/` is dirty after codegen — someone hand-edited it, or forgot to commit the regeneration |
75
+ | Tests | `bun run test` | the node, bare and addon lanes |
76
+ | Library surface compiles | `bun run build:lib` | the compiled export surface breaks |
77
+
78
+ A PR that touches `schema/` and leaves `spec/` stale is the most common red
79
+ here, and it looks nothing like a test failure.
80
+
81
+ ```bash
82
+ gh pr checks <num> --repo tetherto/qvac-core
83
+ gh run view --repo tetherto/qvac-core --log-failed --job <id> > /tmp/pr-<num>-<id>.log
84
+ ```
85
+
86
+ A red `Integrate` is a blocking finding on its own. Read the failing job's log
87
+ before writing a single line of review — half of what looks like a design
88
+ problem is a lint rule.
89
+
90
+ ## What to check, in order
91
+
92
+ Stop at the first tier that produces findings worth the author's time; a review
93
+ that lists twelve nits under a broken contract has buried the real thing.
94
+
95
+ **1. Correctness.** Does it do what the title claims? Trace the changed path
96
+ end to end, including the error path. Look for: a promise not awaited, a
97
+ listener never removed, a resource opened on one path and closed on another, an
98
+ error swallowed into a default.
99
+
100
+ **2. Contract and API.** This is a published package, so an exported signature
101
+ is a promise to a consumer.
102
+
103
+ - Anything added to or changed in the export map, `index.ts`, `types/`, or
104
+ `package.json#exports` — is it intentional, and is it a breaking change?
105
+ - `schema/` or `spec/` changes: is the wire format still compatible, and was the
106
+ baseline regenerated (`bun run build:schema`) rather than hand-edited?
107
+ - Does the change match its own type declarations, and do callers in this repo
108
+ still typecheck?
109
+
110
+ **3. House style.** Run the changed files against **js-house-style** — that
111
+ document, not your own taste. Layering, composition on primitives, module size
112
+ and shape, no defensive programming, comment density.
113
+
114
+ **4. Tests.** A behaviour change with no test is a finding. Name the missing
115
+ case rather than asking for "more tests": the tests live under `test/`, run on
116
+ both the node and bare lanes, and a fix without a regression guard will come
117
+ back.
118
+
119
+ **5. Commit type and title.** Per **pr-create**: is this really a `fix` (a
120
+ defect a consumer of a released version could hit), or is it `chore` on code
121
+ that never shipped? Is the title imperative and specific? Does the branch name
122
+ avoid `codex` / `cursor` / `claude`?
123
+
124
+ **6. Scope.** Does the PR do one thing? A behaviour change mixed with an
125
+ unrelated rename is two PRs — say so, and say which commit to split out.
126
+
127
+ **7. Decision records.** Does the change contradict something in
128
+ `docs/decisions/`? If it does, the record is updated or superseded in the same
129
+ PR, not left to rot. Does it settle something non-obvious with no record at all?
130
+ Say which, and what the record would have to state.
131
+
132
+ ### Do not over-engineer the review
133
+
134
+ The most damaging thing a review can do is talk a good PR into a worse one. AI
135
+ review skews defensive: a guard here, an abstraction there, a layer to absorb a
136
+ hypothetical, each one permanent debt bolted to a problem that never happened.
137
+ That runs directly against the house style, which does not program defensively.
138
+
139
+ It compounds. Successive reviews each add a layer against a different
140
+ speculative case, one review's fix undoes another's, and the code ends up in a
141
+ corner nobody chose.
142
+
143
+ - **Only raise what is wrong now**, or has a concrete path to being wrong.
144
+ "Someone could later..." is not a finding.
145
+ - **Never propose a guard, wrapper, fallback or abstraction** whose only job is
146
+ to make a hypothetical safe. Let caller bugs crash; that is the contract.
147
+ - **Prefer the fix that deletes code.** If your suggestion makes the diff
148
+ bigger, be sure it earns it.
149
+ - **Simplification is a valid finding; speculative hardening is not.**
150
+ - When you cannot tell whether something is real, ask instead of requesting a
151
+ change, and be willing to land zero findings.
152
+
153
+ ## Write the findings
154
+
155
+ Each finding: the file and line, what breaks, and the concrete scenario that
156
+ breaks it. No finding without a failure mode you can state.
157
+
158
+ Drop anything you cannot defend as changing the code, the reviewer's decision,
159
+ or a consumer's experience. Style opinions the house style does not back are
160
+ noise. Say so plainly when the diff is clean: "no `[P1]` or `[P2]`
161
+ findings" is a complete review.
162
+
163
+ Lead with the findings, ordered by severity.
164
+
165
+ ### Severity tags
166
+
167
+ Tag every finding `[P1]`, `[P2]` or `[P3]`. Use the tag, not a word, so two
168
+ reviews of the same repo rank things the same way.
169
+
170
+ - `[P1]` — almost-certain bug, data corruption, security issue, CI breaker, or a
171
+ break of behaviour a consumer relies on. In the overview, and **proposed inline
172
+ by default**.
173
+ - `[P2]` — likely bug, non-obvious caveat, contract or API mismatch, subtle
174
+ behaviour change, missing test on a risky path. In the overview, and **proposed
175
+ inline by default**.
176
+ - `[P3]` — minor: a stale comment or doc, an ergonomic improvement, an optional
177
+ cleanup. In the overview when material, and **not proposed inline** unless the
178
+ user asks for them.
179
+
180
+ **Never silently put a `[P3]` in the inline payload.** A review that posts ten
181
+ nits inline teaches the author to skim the next one.
182
+
183
+ **Severity is what the code does today, not what it might do.** A finding whose
184
+ only support is a scenario nobody has hit is not a `[P2]`: either find the path
185
+ that reaches it, or drop it. Zero findings is a legitimate result.
186
+
187
+ If the user says this is a re-review, say explicitly which earlier concerns are
188
+ resolved and which still stand.
189
+
190
+ ## Posting (PR mode only)
191
+
192
+ 1. Print every proposed comment in chat first: file, line, severity, body.
193
+ The default set is the `[P1]` and `[P2]` findings; name any `[P3]` you are
194
+ holding back so the user can pull it in.
195
+ 2. Ask the user to confirm the exact set. Wait for a clear yes.
196
+ 3. Create the review as **PENDING**, with no event:
197
+
198
+ ```bash
199
+ gh api repos/tetherto/qvac-core/pulls/<num>/reviews \
200
+ --method POST --input /tmp/review.json
201
+ ```
202
+
203
+ where `review.json` has `commit_id` (the `headRefOid` you fetched) and a
204
+ `comments` array of `{path, line, side, body}`, and **no `event` field**. A body
205
+ with `event` submits the review; leaving it out is what makes it pending.
206
+
207
+ 4. Hand the user the link and stop:
208
+ `https://github.com/tetherto/qvac-core/pull/<num>#pullrequestreview-<id>`
209
+
210
+ If a line is not in the diff, GitHub rejects the comment. Anchor to a line the
211
+ patch actually touches, or raise it in the chat overview instead.
212
+
213
+ ## Sibling skills
214
+
215
+ - Writing the PR being reviewed → **pr-create**.
216
+ - The rules tier 3 reviews against → **js-house-style**.
package/CLAUDE.md ADDED
@@ -0,0 +1,45 @@
1
+ # @qvac/core
2
+
3
+ A P2P, multi-device AI workbench core. Three pieces, one duplex stream:
4
+
5
+ - **`Core`** — the state authority. Owns the replicated mesh and the device-local
6
+ store, serves every capability over hrpc. It contains **no AI whatsoever**.
7
+ - **`Client`** — a thin proxy whose methods are generated from the schema.
8
+ Everything an app or assistant does goes through it.
9
+ - **`QvacAssistant`** — the execution host. Owns the AI harness and drives it
10
+ through the Client's capability surface, like any other client. **The only
11
+ place inference happens.**
12
+
13
+ The library runs on both Bare and Node, and both test lanes are real — anything
14
+ that works on only one is a bug. `tui/` is the exception: it imports `bare-tui`
15
+ directly and is Bare-only.
16
+
17
+ ## Durable invariants
18
+
19
+ - **Those three roles do not blur.** AI does not move into `Core`; state
20
+ authority does not move out of it; nothing reaches around `Client`.
21
+ - **`spec/` is generated** by `bun run build:schema`. Never hand-edit it; CI fails
22
+ when it is dirty after regeneration.
23
+ - **Autobee is the source of truth** for replicated state; anything else is a
24
+ materialized view.
25
+ - **History is never evicted to make a prompt fit.** Compaction is the one
26
+ sanctioned exception and it already exists.
27
+
28
+ ## Working here
29
+
30
+ - `bun run lint` (prettier + lunte + tsc) and `bun run test` (node, bare and
31
+ addon lanes) before considering a change done.
32
+ - Tests live in `test/` and run under brittle. A non-trivial change ships tests.
33
+
34
+ ## Always
35
+
36
+ - **Comment only what the code cannot say.** Why, not what. One or two lines,
37
+ never more. Most code needs none — do not narrate it.
38
+ - **Commits read as if a human wrote them.** No `Co-Authored-By` trailer and no
39
+ AI or agent attribution, in a commit message or a PR.
40
+ - **Durable decisions are in `docs/decisions/`.** Read `INDEX.md` when touching an
41
+ area it lists, and open a record only on a path or keyword match — they are
42
+ reference, not rules. Add one when a change makes a non-obvious lasting choice.
43
+ - **Branch from `main`, and open the PR against `main`.** The one exception is a
44
+ stacked PR, which branches from the PR below it and targets that branch.
45
+ - **Branch names never contain `codex`, `cursor` or `claude`**, in any case.
package/README.md CHANGED
@@ -245,11 +245,16 @@ The engine exposes a snapshot chat catalog:
245
245
  const { chats } = await engine.listChats()
246
246
  ```
247
247
 
248
- It returns complete, active mesh chat rows ordered by `createdAt`, then `id` —
249
- pure metadata, so `chatsWatch` only re-emits on create, rename, delete, or flag
250
- changes. The existing replicated chat encoding uses zero as the default for an
251
- absent optional `deletedAt`, so `deletedAt: 0` is not a representable tombstone
252
- and is treated as active. Positive tombstone timestamps are excluded.
248
+ It returns complete, active mesh chat rows in sidebar order, bottom first
249
+ (clients reverse to render): a chat sits where the user last dragged it
250
+ (`moveChat`) until a chunk lands in it, then most-recently-active wins; `id`
251
+ breaks ties. Groups ride the same frame, top first (`moveChatGroup` orders
252
+ them). Recency is derived from the chunk counter and costs no write, but it is
253
+ part of the row, so `chatsWatch` re-emits on any change to the rendered list:
254
+ create, rename, delete, flag, placement, or a chunk landing. The existing
255
+ replicated chat encoding uses zero as the default for an absent optional
256
+ `deletedAt`, so `deletedAt: 0` is not a representable tombstone and is treated
257
+ as active. Positive tombstone timestamps are excluded.
253
258
  `listChats()` itself is a snapshot query. Chat create, update, delete, and watch
254
259
  capabilities are available through the typed chat API.
255
260
 
@@ -17,10 +17,10 @@ export function createAgentsApi(current, deviceId) {
17
17
  };
18
18
  return {
19
19
  createAgent: async (input) => {
20
- const mesh = await requireMesh(current);
20
+ const mesh = await requireMesh(current, input.meshId);
21
21
  return withOrphaned(mesh, await createAgent(mesh, input));
22
22
  },
23
- listAgents: async () => list(await requireMesh(current)),
23
+ listAgents: async (request) => list(await requireMesh(current, request?.meshId)),
24
24
  getAgent: async ({ id }) => {
25
25
  const mesh = await requireMesh(current);
26
26
  return withOrphaned(mesh, await mustGetActiveAgent(mesh, id));
@@ -33,6 +33,6 @@ export function createAgentsApi(current, deviceId) {
33
33
  const mesh = await requireMesh(current);
34
34
  return withOrphaned(mesh, await deleteAgent(mesh, deviceId, id));
35
35
  },
36
- agentsWatch: watchable('agentsWatch', () => requireMesh(current), (_request, mesh) => list(mesh))
36
+ agentsWatch: watchable('agentsWatch', (request) => requireMesh(current, request?.meshId), (_request, mesh) => list(mesh))
37
37
  };
38
38
  }
@@ -1,5 +1,5 @@
1
1
  import type { CapabilityHandlers } from '../../spec/capabilities.d.ts';
2
2
  import { type CurrentMesh } from './current-mesh.ts';
3
- type ChatGroupCapabilities = Pick<CapabilityHandlers, 'createChatGroup' | 'listChatGroups' | 'renameChatGroup' | 'deleteChatGroup' | 'setChatGroup'>;
3
+ type ChatGroupCapabilities = Pick<CapabilityHandlers, 'createChatGroup' | 'listChatGroups' | 'renameChatGroup' | 'deleteChatGroup' | 'setChatGroup' | 'moveChat' | 'moveChatGroup'>;
4
4
  export declare function createChatGroupsApi(current: CurrentMesh): ChatGroupCapabilities;
5
5
  export {};
@@ -1,5 +1,5 @@
1
- import { createChatGroup, deleteChatGroup, listChatGroups, renameChatGroup } from "../core/chat-group.js";
2
- import { setChatGroup } from "../core/chat.js";
1
+ import { createChatGroup, deleteChatGroup, listChatGroups, moveChatGroup, renameChatGroup } from "../core/chat-group.js";
2
+ import { moveChat, setChatGroup } from "../core/chat.js";
3
3
  import { requireMesh } from "./current-mesh.js";
4
4
  export function createChatGroupsApi(current) {
5
5
  return {
@@ -7,6 +7,8 @@ export function createChatGroupsApi(current) {
7
7
  listChatGroups: async () => listChatGroups(await requireMesh(current)).then((groups) => ({ groups })),
8
8
  renameChatGroup: async ({ id, name }) => renameChatGroup(await requireMesh(current), id, name),
9
9
  deleteChatGroup: async ({ id }) => deleteChatGroup(await requireMesh(current), id),
10
- setChatGroup: async ({ id, groupId }) => setChatGroup(await requireMesh(current), id, groupId)
10
+ setChatGroup: async ({ id, groupId }) => setChatGroup(await requireMesh(current), id, groupId),
11
+ moveChat: async ({ id, groupId, afterId }) => moveChat(await requireMesh(current), id, { groupId, afterId }),
12
+ moveChatGroup: async ({ id, afterId }) => moveChatGroup(await requireMesh(current), id, { afterId })
11
13
  };
12
14
  }
@@ -11,13 +11,13 @@ export function createChatApi(current, deviceId) {
11
11
  const chatActivity = (mesh, chatIds) => listChatActivity(mesh, chatIds ?? undefined).then((activities) => ({ activities }));
12
12
  return {
13
13
  createChat: async (input) => createChat(await requireMesh(current), input),
14
- listChats: async () => chatList(await requireMesh(current)),
14
+ listChats: async (request) => chatList(await requireMesh(current, request?.meshId)),
15
15
  getChat: async ({ id }) => mustGetActiveChatListing(await requireMesh(current), id),
16
16
  renameChat: async ({ id, title }) => renameChat(await requireMesh(current), id, title),
17
17
  setChatRagEnabled: async ({ id, enabled }) => setChatRagEnabled(await requireMesh(current), id, enabled ?? false),
18
18
  setChatWebSearchEnabled: async ({ id, enabled }) => setChatWebSearchEnabled(await requireMesh(current), id, enabled ?? false),
19
19
  deleteChat: async ({ id }) => deleteChat(await requireMesh(current), deviceId, id),
20
- chatsWatch: watchable('chatsWatch', () => requireMesh(current), (_request, store) => chatList(store)),
20
+ chatsWatch: watchable('chatsWatch', (request) => requireMesh(current, request?.meshId), (_request, store) => chatList(store)),
21
21
  listChatActivity: async (input) => chatActivity(await requireMesh(current), input?.chatIds),
22
22
  chatActivityWatch: watchable('chatActivityWatch', () => requireMesh(current), (request, store) => chatActivity(store, request?.chatIds)),
23
23
  searchChats: async (input) => {
@@ -1,5 +1,6 @@
1
1
  import type { Mesh } from '../core/mesh.ts';
2
- export type CurrentMesh = () => Mesh | null | Promise<Mesh | null>;
2
+ export type CurrentMesh = (meshId?: string | null) => Mesh | null | Promise<Mesh | null>;
3
3
  export declare const NO_ACTIVE_MESH = "no active mesh";
4
- export declare function requireMesh(current: CurrentMesh): Promise<Mesh>;
4
+ export declare const NO_SUCH_MESH = "no such mesh";
5
+ export declare function requireMesh(current: CurrentMesh, meshId?: string | null): Promise<Mesh>;
5
6
  export declare function isMeshTransition(err: unknown): boolean;
@@ -1,8 +1,9 @@
1
1
  export const NO_ACTIVE_MESH = 'no active mesh';
2
- export async function requireMesh(current) {
3
- const mesh = await current();
2
+ export const NO_SUCH_MESH = 'no such mesh';
3
+ export async function requireMesh(current, meshId) {
4
+ const mesh = await current(meshId);
4
5
  if (!mesh)
5
- throw new Error(NO_ACTIVE_MESH);
6
+ throw new Error(meshId ? `${NO_SUCH_MESH}: ${meshId}` : NO_ACTIVE_MESH);
6
7
  if (!mesh.opened)
7
8
  await mesh.ready();
8
9
  return mesh;
@@ -20,6 +20,7 @@ function toEngineDevice(device, overrides = {}) {
20
20
  appBuild: device.appBuild,
21
21
  appChannel: device.appChannel,
22
22
  platform: device.platform,
23
+ memberId: device.memberId,
23
24
  ...overrides
24
25
  };
25
26
  }
@@ -17,6 +17,7 @@ import { createFilesApi } from "./files.js";
17
17
  import { createLogsApi } from "./logs.js";
18
18
  import { instrument } from "./instrument.js";
19
19
  import { watchable } from "./watchable.js";
20
+ import { createMembersApi } from "./members.js";
20
21
  import { createMeshApi } from "./mesh.js";
21
22
  import { createNetworkApi } from "./network.js";
22
23
  import { createNotificationsApi } from "./notifications.js";
@@ -64,6 +65,7 @@ export function createApi(deps = {}) {
64
65
  })
65
66
  : null),
66
67
  ...(deps.meshStatus ? createMeshApi(deps.meshStatus) : null),
68
+ ...(mesh ? createMembersApi(mesh) : null),
67
69
  ...(deps.network ? createNetworkApi(deps.network) : null),
68
70
  ...(deps.diagnostics ? createDiagnosticsApi(deps.diagnostics) : null),
69
71
  ...(deps.logs ? createLogsApi(deps.logs) : null),
@@ -0,0 +1,3 @@
1
+ import { type CurrentMesh } from './current-mesh.ts';
2
+ import type { CapabilityHandlers } from '../../spec/capabilities.d.ts';
3
+ export declare function createMembersApi(current: CurrentMesh): Pick<CapabilityHandlers, 'listMembers'>;
@@ -0,0 +1,23 @@
1
+ import { requireMesh } from "./current-mesh.js";
2
+ const MEMBERS = '@qvac/members';
3
+ export function createMembersApi(current) {
4
+ return {
5
+ listMembers: async () => {
6
+ const mesh = await requireMesh(current);
7
+ const snap = mesh.view.snapshot();
8
+ try {
9
+ const members = await snap.find(MEMBERS).toArray();
10
+ return {
11
+ members: members.map((member) => ({
12
+ id: member.id,
13
+ name: member.name,
14
+ joinedAt: member.joinedAt
15
+ }))
16
+ };
17
+ }
18
+ finally {
19
+ await snap.close();
20
+ }
21
+ }
22
+ };
23
+ }
@@ -1,5 +1,10 @@
1
- import type { AssistantMeshStatus } from '../../spec/hyperschema/types.d.ts';
1
+ import type { AssistantMeshList, AssistantMeshStatus } from '../../spec/hyperschema/types.d.ts';
2
2
  import type { CapabilityHandlers } from '../../spec/capabilities.d.ts';
3
+ export interface MeshInviteResult {
4
+ readonly invite?: string;
5
+ readonly meshId?: string;
6
+ readonly notice?: string;
7
+ }
3
8
  export interface MeshStatusSource {
4
9
  watch(listener: () => void): void;
5
10
  unwatch(listener: () => void): void;
@@ -8,6 +13,12 @@ export interface MeshStatusSource {
8
13
  acknowledgeKicked(): void;
9
14
  join(invite: string): Promise<void>;
10
15
  cancelJoin(): void;
11
- invite(): Promise<string | null>;
16
+ invite(member?: boolean, meshId?: string): Promise<MeshInviteResult>;
17
+ list(): Promise<AssistantMeshList>;
18
+ open(meshId: string): Promise<void>;
19
+ select(meshId: string): Promise<void>;
20
+ close(meshId: string): Promise<void>;
21
+ label(meshId: string, label: string): Promise<void>;
22
+ createRoom(): Promise<string>;
12
23
  }
13
- export declare function createMeshApi(status: MeshStatusSource): Pick<CapabilityHandlers, 'meshStatusWatch' | 'leaveMesh' | 'acknowledgeKicked' | 'joinMesh' | 'cancelMeshJoin' | 'meshInvite'>;
24
+ export declare function createMeshApi(status: MeshStatusSource): Pick<CapabilityHandlers, 'meshStatusWatch' | 'listMeshes' | 'meshesWatch' | 'openMesh' | 'selectMesh' | 'closeMesh' | 'leaveMesh' | 'acknowledgeKicked' | 'joinMesh' | 'cancelMeshJoin' | 'meshInvite' | 'setMeshLabel' | 'createRoom'>;