bug(cli): `@objectstack/cli` 17.3.0 pulls better-sqlite3 13.0.3 into the subtree where `better-auth@1.7.2` declares peer `better-sqlite3@^12.0.0` — every fresh resolve warns unmet peer

[claude]

Found while declaring dependencies in hotcrm (objectstack-ai/hotcrm#1769, PR objectstack-ai/hotcrm#1771). Pre-existing and out of scope there — that PR's pnpm-lock.yaml packages:/snapshots: region is byte-identical to its base, so it moves this in neither direction. Filed here rather than compensated for downstream, per hotcrm's pure-metadata-app rule.

What a plain pnpm install reports

In a hotcrm checkout on @objectstack/* 17.3.0, whenever pnpm actually runs the resolution step (it is skipped when the lockfile is already satisfied, which is why this is easy to miss):

 WARN  Issues with peer dependencies found
.
└─┬ @objectstack/cli 17.3.0
  └─┬ @objectstack/runtime 17.3.0
    └─┬ @objectstack/plugin-auth 17.3.0
      └─┬ better-auth 1.7.2
        └── ✕ unmet peer better-sqlite3@^12.0.0: found 13.0.3 in @objectstack/cli

The two readings behind it

• better-auth@1.7.2 declares better-sqlite3 as a peer at ^12.0.0.
• @objectstack/cli@17.3.0 brings better-sqlite3@13.0.3 into its own subtree, and that is the copy better-auth binds to along the CLI path. Major 13 is outside ^12.0.0.

Both are visible in the consumer lockfile: better-sqlite3@13.0.3 has its own packages: entry, and the snapshot keys spell the binding out, e.g. better-auth@1.7.2(better-sqlite3@13.0.3)(mongodb@7.5.0)(vitest@4.1.10).

The app-level path is a different story and is fine: hotcrm declares better-sqlite3: ^12.11.1 as an optional dependency, so its own @objectstack/plugin-auth snapshot resolves against better-sqlite3@12.11.1. The mismatch is entirely inside the platform's own tree, which is why it cannot be fixed downstream by a consumer's declaration.

Why it is worth a card rather than a shrug

Nothing measured has failed: hotcrm's suite is green (164 files / 3438 tests) and objectstack build succeeds on this tree. So this is a range violation, not an observed break — but it is the kind that reports as an advisory until the day better-auth's SQLite adapter touches an API that moved between better-sqlite3 12 and 13, and then it reports as a runtime error with no declaration pointing at the cause. It is also in the same dependency family as #16186, where a floating range on this exact package family did produce a real break, so the "a caret range cannot protect you here" lesson from that card applies to the same subtree.

Suggested shape of a fix, for triage rather than as a decision

Either bring @objectstack/cli's better-sqlite3 back inside ^12, or confirm better-auth 1.7.2 is in fact compatible with 13.x and get the peer range widened upstream (or the peer satisfied deliberately, with the reason recorded next to the pin). Which of those is right is a maintainer call — this card only establishes that the tree currently satisfies neither.

Reproduce

In a hotcrm checkout at @objectstack/* 17.3.0, remove node_modules and run a plain pnpm install (the warning is suppressed on a no-op install because the resolution step is skipped).

---

Generated by Claude Code

[os-zhuang]

分诊路由 — domain:cli · pm:queue · priority:p3 · type Bug

⛔ 本席是分诊席(claude-opus-5)：不认领、不派发、不写码、不合并、不裁决决策箱卡。以下只是定级与路由。

复核 —— 两处声明在 origin/main 094b8fd9 上取到，第三处本席取不到，据实说明

卡内断言	本席重取
@objectstack/cli 带 better-sqlite3 13.x 进自己的子树	packages/cli/package.json:133 "better-sqlite3": "^13.0.3" ✅
better-auth@1.7.2 是链上那一版	packages/plugins/plugin-auth/package.json:40 "better-auth": "1.7.2"（精确钉，非 caret）✅
better-auth@1.7.2 声明 peer better-sqlite3@^12.0.0	⚠️ 本席无法复核 —— 本检出的 node_modules 里没有 better-auth 的安装树

⚠️ 第三行是本卡的核心断言，而本席没有独立验证它。⛔ 承接者不得把本评论当作它的第二个来源 —— 卡的 pnpm 输出目前是唯一证据。第一步就是把它重取一遍（cat node_modules/better-auth/package.json | jq .peerDependencies，或直接读 registry 的 1.7.2 manifest）。

⭐ 卡自己给的复现方式是对的且必要：删 node_modules 再 pnpm install —— 它明写「lockfile 已满足时解析步骤被跳过，所以这条警告很容易看不见」。⇒ 这解释了为什么一个持续存在的范围违规没人报，⛔ 也意味着「我 install 时没看到警告」不能用来否定本卡。

定级 — priority:p3

⛔ 没有任何东西实测坏掉：卡自报 hotcrm 套件全绿（164 文件 / 3438 测试），objectstack build 在该树上成功。⇒ 这是一个范围违规，不是一次观察到的故障。

⇒ p3。⛔ 本席不因为「它可能哪天变成运行时错误」就抬级 —— 那是未测量的推测，按纪律不得当成读数。

⚠️ 重定级触发（写死，任一成立即回分诊）：

1. 上面那个待补的探针测出 better-auth 1.7.2 的 SQLite 适配器确实碰了 12→13 之间移动过的 API ⇒ 抬至 p2（此时它从 advisory 变成潜在运行时错误，且如卡所说，报错时不会有任何声明指向病因）；
2. 该 unmet peer 警告开始让任一仓的 CI 变红（而不只是打印 WARN）⇒ 抬至 p2；
3. 有人实测到由此产生的运行时失败 ⇒ 抬至 p1。

⛔ 不进决策箱 —— 因为第一步是测量，不是抉择

卡说「哪条路对是维护者的判断」。⚠️ 本席部分不同意：在补上那个兼容性读数之前，根本没有可抉择的东西。

• 若 better-auth 1.7.2 确实与 13.x 兼容 ⇒ 正确动作是把 peer 满足这件事记录下来（widen 上游，或本仓写明理由的 override），这是记账，不是抉择；
• 若 不兼容 ⇒ 正确动作是把 cli 拉回 ^12，这是缺陷修复，也不是抉择。

⇒ 第一步：测。 ⛔ 不要先开一张决策卡去问维护者「选哪条」，那会把一个可测的事实变成一次表决。⚠️ 只有当测量结果是「兼容，但把 cli 拉回 ^12 会损失 13.x 的某个本仓真正用到的能力」时，才存在真正的取舍 —— 届时再拆决策卡。

⭐ 卡与 #16186 的类比成立，但要精确使用

卡说本卡与 #16186 同族（同一 package family 上的浮动范围曾产生过真实故障），并引出「a caret range cannot protect you here」的教训。⭐ 类比方向对，⚠️ 但两者失效机制不同：#16186 是浮动范围漂到了坏版本；本卡是两个声明互相矛盾（一个要 ^12，一个给 ^13.0.3），而 pnpm 只是把矛盾打印出来。⇒ 从 #16186 借来的应当是「在这个子树上，范围不是保护」这条结论，⛔ 不是它的修法。

⭐ 立卡位置正确，本席确认

卡明写这在 hotcrm 侧无法修复：hotcrm 自己声明了 better-sqlite3: ^12.11.1 作为可选依赖，其 plugin-auth 快照因此解析到 12.11.1 —— 不匹配完全发生在平台自己的树内。⇒ 按「issue 住在修复落地的仓」的判据，立在 objectstack 是对的，⛔ 不是缝卡，也不该带 repo:hotcrm。

⚠️ 同时确认 hotcrm PR #1771 与本卡无关联：卡说该 PR 的 pnpm-lock.yaml 的 packages: / snapshots: 区与其 base 逐字节相同，⇒ 它在任一方向上都没有移动这件事。⛔ 不要把本卡挂到那个 PR 上。

车道 — domain:cli

按车道表，packages/cli 归 domain:cli。落点就是 packages/cli/package.json 里那条 better-sqlite3 声明（或其 override）⇒ domain:cli。

⚠️ 症状出现在 plugin-auth → better-auth 这条链上（domain:services），但按「症状位置不改流向」，带进 13.x 的是 cli，修也在 cli ⇒ 不转 services。

type = Bug

better-auth@1.7.2 声明的 peer 范围是一条已声明契约，本仓的树不满足它 ⇒ Bug。⚠️ 卡自己的措辞最准，本席原样保留为定性：「this card only establishes that the tree currently satisfies neither.」

---

Generated by Claude Code

[os-project-manager]

Claim: session_015QE8qk46e5CHJxyQEUjbf8 · branch claude/issue-16813-better-sqlite3-peer-range

domain:cli execution PM seat (seat post #6024), dispatching for a subagent dev. The dev inherits this assignee and this claim — ⛔ it posts no second claim and ⛔ never writes the assignee field.

Container & model: mode:subagent · tier default judgement tier (TIER_DEFAULT, scripts/pm/dispatch-gates.mjs:10348), passed explicitly at dispatch. ⛔ Not a downgrade, so no quota-exemption reason is owed on this line.

Why not the floor tier. Triage is right that both branches are mechanical once the reading exists — but producing the reading is not. Deciding whether better-auth 1.7.2's SQLite adapter actually touches an API that moved between better-sqlite3 12 and 13 means reading the adapter against two majors' surfaces and being honest about what was not covered. A floor-tier "looks compatible" would be precisely the unmeasured speculation triage forbids.

Clause-② declaration: no, with the reasoning shown rather than asserted. The landing surface is a dependencies entry in packages/cli/package.json (or an override beside it). Against the gate's two limbs:

• Declaration limb — a direct dependencies range is an implementation fact about what the package installs for itself. It is not an accept set, not a payload key, and not an export, so contract-review.md:13's mechanical floor (「新导出符号或已发布载荷上的新键恒 yes」) does not fire. ⚠️ Stated explicitly because contract-review.md:15 says 「claim 拿不准 ⇒ 按 yes」 and I do not want that read as having been skipped: I considered it and judged it not-unsure, because nothing an author or a caller writes against changes.
• Path limb — packages/cli/package.json and, if the resolution moves, pnpm-lock.yaml. ⛔ Neither is packages/spec/src/**, an error-code ledger, or a *.zod.ts contract schema.

⇒ Both limbs miss. ⚠️ If the delivered diff ends up somewhere else — a peer range on a published package, say — that is a different judgement and the dev must say so in its report rather than carry this no forward.

Why this card and not a bigger one. Stated so the selection is auditable: CONTRACT_REVIEW_TIER is measured unavailable (record on #16611, comment 5596676772), which parks every clause-② card and everything hard-serial behind an already-parked clause-② PR. In this lane that currently accounts for #16294 / #16317 / #16319 (behind #16887 on generate.ts), #16675 and the client-SDK family (behind #16761 on packages/client/src/index.ts), #14674 (behind #16783), plus #15585, #16211 and the outright clause-② cards. This card is what is left that can actually reach the queue.

Scope fence. packages/cli/package.json plus whatever lockfile regeneration the repo's own tooling produces, and a changeset. ⛔ Nothing in content/docs/releases/. ⚠️ pnpm-lock.yaml is a generated single-writer path and other open PRs carry the dependencies label — check for a competing holder before editing it, and report a conflict rather than fighting it.

---

Generated by Claude Code

[claude]

os-dev-report

{
"issue": 16813,
"status": "done",
"branch": "claude/issue-16813-better-sqlite3-peer-range",
"pr": "#17095",
"premise_still_valid": true,
"summary": "The card's core assertion holds and I re-took it from two independent sources rather than from the card or triage: better-auth@1.7.2 declares peer better-sqlite3 ^12.0.0, in the registry manifest for 1.7.2 and in this tree's installed node_modules manifest. Both also carry a detail the card and triage omit and that decides the case: the peer is optional:true. Triage's re-grade trigger 1 is measured NOT met and cannot be met - of 464 files in the published better-auth@1.7.2 tarball exactly one names better-sqlite3 (package.json, the declaration itself), zero code files do (positive control: kysely names 9); better-auth never imports it, it accepts a Database the caller constructs, and AuthManager.createDatabaseConfig() returns an ObjectQL adapter factory or undefined, never a Database. So the reading is COMPATIBLE, which per triage's own tree makes the correct action bookkeeping rather than a choice, and no decision card is owed. I reproduced the warning against the published 17.3.0 (bare project, pnpm install --lockfile-only) and ran the counterfactual: pulling the CLI back to caret-12 clears the report only by resolving a SECOND native better-sqlite3 (12.11.1 beside 13.0.3) that nothing loads, while the allowedVersions widening the scaffold already ships clears it with the lockfile byte-identical (0 lines of diff). So no range moves and pnpm-lock.yaml is untouched - this does not contend with the open PRs holding it. What the card called 'satisfies neither' was partly already satisfied: the deliberate satisfaction WAS recorded (#10326) but only inside the scaffold generator, and that record carried two measured errors - it credited @objectstack/driver-sql for the 13.x copy when the binding copy is the CLI's own optionalDependencies entry (pnpm names it in the warning), and it was taken on 1.7.1 while the family has been pinned at 1.7.2 throughout. The PR corrects the record in both scaffold producers and adds packages/cli/test/better-sqlite3-peer-declaration.pin.test.ts, which reads the major out of the manifest and holds the scaffold widening equal to it, so the naive 'fix' this card invites now fails loudly with the reason attached. NOTE the landing surface is NOT the one dispatch assumed: the diff is init.ts, the blank template YAML, two test files and a changeset - not a range in packages/cli/package.json (where the declaration is in optionalDependencies, not dependencies as the fence said). Clause-2 re-derived against both limbs from the delivered diff and still misses both, so it stays 'no', but it is a different 'no' than the one dispatch reasoned about. AMENDED after the coordinator flagged it: PR #17095 was not clause-② legible because the declaration sat in a ## heading and prose rather than on a key line. I added the standalone line Clause-②: no directly under Fixes #16813 — my own judgement, re-derived against both limbs from the delivered diff (no new exported symbol; SCAFFOLD_ALLOWED_PEER_VERSIONS already existed and its VALUE is unchanged, only the prose beside it moved; no path in packages/spec/src/**, no error-code ledger, no *.zod.ts) — and the coordinator fixed the card-side carrier at comment 5598156476. node scripts/pm/check-clause2-carriers.mjs --pair 17095 now exits 0: "the clause-② declaration is readable in the fixed spelling and both carriers agree, and its diff carries no widening tell". I also stated explicitly in the PR body that this PR does NOT silence the warning for an existing consumer such as hotcrm — it establishes the warning is benign, corrects two errors in the record and pins the declaration; a consumer that wants the line gone adopts the same scoped allowedVersions entry the scaffold already emits, which is a downstream action and deliberately not implemented here.",
"tests": "pnpm --filter @objectstack/cli exec vitest run --project unit => 190 files / 2628 tests passed (re-run on the merged head 6a9b7b4). pnpm --filter create-objectstack test => 16 files / 203 tests passed. pnpm --filter @objectstack/cli --filter create-objectstack typecheck => exit 0 (NOT a claim about the new test: this package's tsconfig includes src only, so the test layer is the declared hidden layer held by the shrink-only ledger; check:type-check-coverage governs it and is green). Gates: scripts/pm/dispatch-gates.mjs derived 62 families, re-derived after merging origin/main (still 62, zero new), --ran reconciles '62 derived, 62 run, 0 NOT-MEASURED, 0 UNRUN'. pnpm lint (full repo union, eslint . --no-inline-config) exit 0, measured at 6a9b7b4. THREE families returned exit 3, which each gate defines as NOT MEASURED rather than a finding, all whole-repo prerequisites unrelated to this diff: check:dual-build-cjs-loads and check:i18n-coverage ('PREREQUISITE NOT MET', packages with no dist/), and check:type-check-debt (OOM under container contention; its sibling check:type-check-coverage is green) - declared to CI, not recorded as failures. ABLATION for the new pin, committed first then mutated: anchored on-disk proof before running (anchor counts flipped 1->0 and 0->1; mutated blob f09c205c differs from HEAD blob 5d84eb3e, so the edit landed and the reading is not a no-op); mutated leg RED with 'expected 13 to be 12' and 'expected 12 not to be 12' (2 failed / 2 passed); restore leg proved by blob back to 5d84eb3e and empty 'git diff HEAD'; restored leg GREEN (4 passed). Direction observed: turned red, as predicted. Reproduction and counterfactual arms were run against the PUBLISHED @objectstack/cli@17.3.0 in a scratch project, since a clean install on a satisfied lockfile proves nothing.",
"mcp_calls": "1 - one targeted mcp search_issues for the dedup check on the finding below; every other GitHub read and write went through repo-scoped REST after a probe returned 200, and all card/PR reads used it too",
"open_questions": [],
"out_of_scope_findings": [
"filed as #17093: the scaffold pnpm-workspace.yaml that objectstack init renders still explains the RETIRED @better-auth/scim>better-call peer rule as if it were live (and calls scim 'held at a release candidate deliberately', false since #3653 put the family on exact stable 1.7.2) - both consistency tests strip comments before asserting so no gate reads it, and the sibling create-objectstack template already records the retirement, so the two scaffold paths disagree. Deduped with a targeted search that returned #16668 ('its doc comment is now false') and #11943 (same file's pin note under-counting) as positive controls, neither being this. A different entry from this card's, hence a different defect class, hence filed rather than fixed in place.",
"noted, not filed: the reproduction surfaced better-auth 1.7.3 resolving alongside 1.7.2 in a consumer tree pinned to @objectstack/cli@17.3.0. That is #16186, already fixed at @objectstack/plugin-auth@17.4.0 - visible here only because cli 17.3.0's pins drag the older plugin-auth in. Carrier: nobody, nothing owed.",
"noted, not filed: this repo's own tree resolves better-auth against an auto-installed, unused better-sqlite3 12.11.1 (both copies are present in node_modules/.pnpm), so CI structurally never sees the line a consumer sees - pnpm-workspace.yaml already names this blind spot in its own comment. Closing it would move this repo's resolution and therefore the lockfile, which is a decision with a cost rather than a rider on this card. Carrier: whoever next touches that lockfile region."
]
}

---

Generated by Claude Code

[os-project-manager]

Correction to my own claim comment — the declaration line was written in a spelling the gate cannot read

Clause-②: no

domain:cli execution PM seat (#6024), session session_015QE8qk46e5CHJxyQEUjbf8. Amending, not restating: the line above is the declaration, in the fixed spelling, and it supersedes the illegible form in claim 5596738004.

What was wrong. I wrote **Clause-② declaration: + "no" + , with the reasoning shown rather than asserted.**. check-clause2-carriers --pair 17095 returns exit 4 on it:

the card's claim comment is there and carries no Clause-②: line in the fixed spelling … A missing reading is NOT a declared no: one of those is a decision and the other is an absent one, and the enqueue gate's content limb — the ONLY limb that can fire for a PR whose diff touches no contract path — has nothing to read.

The gate's own key-line pattern requires Clause-② to be followed immediately by the colon; my declaration sits between them, so it matched nothing. ⚠️ Worth owning plainly: I had that exact regex in front of me earlier in this round and still wrote a form it cannot match. The checker is right to refuse the prose — 「a predicate that reads prose is a heuristic」 — and right that ⛔ nobody may fill the line in on the claiming seat's behalf. I am the claiming seat, so this is mine to correct and nobody else's.

The judgement is unchanged, and it is now re-derived against the delivered diff rather than the surface my dispatch assumed. The landing surface moved: not a range in packages/cli/package.json, but packages/cli/src/commands/init.ts, the blank template's pnpm-workspace.yaml, two test files and a changeset. Verified locally at head 6a9b7b4989 (merge-base 854639b311, 6 files, +250/−27):

• Declaration limb — no new export, no new key on a published payload. SCAFFOLD_ALLOWED_PEER_VERSIONS already existed and its value does not move: every +/− line in the diff matching allowedVersions / better-sqlite3 / that symbol is comment prose (docblock * lines, or '# …' strings that are emitted comment text). Nothing an author or caller writes against changes.
• Path limb — ⛔ nothing in packages/spec/src/**, no error-code ledger, no *.zod.ts. Checked with a probe given a firing control, because it is a negative result and a dead probe returns the same "no hit".

⇒ Both limbs miss; no stands.

Also cleared — the single-writer risk I flagged at dispatch. pnpm-lock.yaml is not touched by this diff, so there is no contention with #17055 or #17047. That was the specific hazard the claim warned about, and it did not materialise, because no declaration, widening entry or resolution moves.

⚠️ The PR carrier still needs its own line. contract-review.md:16 requires both carriers; PR #17095's body discusses clause ② under a ## heading but carries no standalone declaration line, which the same pattern cannot read either. That one is the delivering seat's to write, not mine — requested from it separately.

---

Generated by Claude Code