Skip to content

[PR] release: land the TRUE v3 gate-branch publish model (v2 arm self-fired at #4654) - #4660

Merged
ranxianglei merged 7 commits into
masterfrom
v3-gate-finalize
Oct 25, 2026
Merged

ranxianglei merged 7 commits into
masterfrom
v3-gate-finalize

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What this is

The true v3 document set (release-bugfix.yml dual path + ci.yml FULL-scope-for-bugfix + reference/release.md rules), developed as #4653 but merged before the v3 push landed: #4653 captured the pre-v3 head at 07:43:21Z, so master and every live tree still run the v2 wide trigger ("any same-repo merge into a bugfix-v* lane publishes").

Why it matters right now (incident, 2026-10-25 07:43–08:09Z)

Merging arming PR #4654 resolved its own pull_request_target close event against the base ref after the merge landed → the arm triggered itself → run 40173869038 ran the full guard+CI chain and published v0.1.207 (tag = post-merge head 7e69b49f, GH Release 08:09:37Z, npm billion-context now 0.1.207). The shipped tree lacks advisory bc-2026-001 (#4655 never merged). The old lane is frozen by the monotonic npm guard — later closes into it die red at "not strictly newer than latest", zero npm churn — but the v2 doc still live on master would re-fire any future lane merge if a lane were ever cut from it again. Root cause documented in reference/release.md ("Why v3 has no arming step"): an arming commit whose trigger matches its own target fires itself.

What changes

  • Trigger: pull_request_target closed branches [bugfix, master], dual resolve paths: A) PUBLISH on ship PR (base=bugfix, head=bugfix-vX.Y.Z) of the POST-MERGE lane head; B) AUTO-CUT next lane when the alignment PR (head=bugfix, contract title) merges into master. Every other close = millisecond no-op. Legacy carve-out stays dormant; fast dispatch retained; permissions/secret surface unchanged.
  • ci.yml: push+PR whitelist gains bugfix; plan job forces FULL scope when PR base = bugfix (ship PRs run the complete suite; e2e lanes ride the ci:full label as before).
  • No src/kernel/test files touched — workflows + docs only. YAML parse-checked locally (both files clean, 1 job / 20 steps).

Cycle impact after this lands

No arming ever again: the bugfix gate branch is born carrying v3, tag lanes are cut from aligned master (which will then contain this doc), and only the one ship-PR shape can fire. Advisory bc-2026-001 rides into the next release (0.1.208).

… next lane on alignment merge)

- release-bugfix.yml: THE FIRE is now exactly one PR shape — a same-repo MERGED PR base=bugfix head=bugfix-vX.Y.Z publishing its post-merge lane head. Merging carries INTO a lane publishes nothing (kills the 'any merge into the lane ships' hazard). Second path: a merged alignment PR (head=bugfix, base=master, title contract 'align master with vX.Y.Z (shipped from <lane>)') AUTO-CUTS the next lane bugfix-vX.Y.Z from tag vX.Y.Z with package.json pre-bumped +1 patch (stage P4; idempotent; failure posts manual recovery and fails loudly). Alignment PR now heads from bugfix -> master. All version guards / full-CI dispatch+wait / fast dispatch escape hatch / legacy dormant carve-out path unchanged.

- ci.yml: 'bugfix' added to push+pull_request branch lists; plan scope forces FULL matrix for base=bugfix ship PRs (born full-scope like #3688 release PRs). e2e lanes are label-gated (ci:full), so the ship PR gets that label at open time — no e2e yml changes needed.

- reference/release.md: gate-branch model v3 (roles of bugfix / tag lanes / master, P0-P4 cycle, alignment title contract, protection payload incl. context-roster rule), dual-lane section aligned (auto-cut, ship PR lane->bugfix, CI wiring v3).
@github-actions

github-actions Bot commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: v3-gate-finalize (a7db582)

Latest build — install this exact version

npm install -g billion-context@0.0.5708-pr.4660.fa7e95d

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit version build
a7db582 billion-context@0.0.5708-pr.4660.fa7e95d build
7ad6810 billion-context@0.0.5707-pr.4660.a1446fd build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr4660.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm/qwen3.8-27b)

查重: 不重复 — searched open+closed issues/PRs for "gate-branch" / "arming" / "release-bugfix": this PR (#4660) is the only open item on the v3 gate-branch publish model. Related but distinct lineage: #4653 (merged v2 lane-publish doc — the predecessor whose wide trigger caused the incident), #4654 (the arming PR that self-fired and published v0.1.207 — closed), #4659 (open companion: align master with the shipped v0.1.207 tree — different scope), #4477/#4500/#4467 (closed design discussions that led to the dual-lane model).

标签: bug + scope/ci + p2 (release-pipeline defect — v2 wide trigger can self-fire again if a lane is ever cut from pre-v3 master; currently contained by the monotonic npm guard; workaround = don't cut lanes until this lands).

This is a [PR] issue tracking existing PR #4660 (branch v3-gate-finalize @ 7ad6810) — not redoing it. Status so far: pulled the branch, diff is exactly the 3 claimed files (.github/workflows/ci.yml, .github/workflows/release-bugfix.yml, reference/release.md; +372/−197, no src/kernel/test touched). CI on head: all guard/gate jobs green (static-gates, version-guard, kernel-guard, pi-subagents-guard, docs-sync, docs-coverage, config-surface-guard, lock-sync, lane-guard, lifecycle-ledger-guard, test-import-graph, unused-exports, mysql-contract); e2e lanes skipped as designed (no ci:full label); the 15 test shards still in_progress.

Now doing the full review of the trigger logic against the incident timeline; will post the structured verdict (eight questions) once the test shards finish.

@ranxianglei ranxianglei added bug Something isn't working p2 scope/ci labels Oct 25, 2026
ci-check added 4 commits October 25, 2026 17:03
…4660)

Review of the v3 model found the guard deadlocks the cycle at P3: the
auto-opened alignment PR (head=bugfix, base=master) legitimately carries
the shipped version bump into master, and backport carry branches inherit
the lane pre-bump — neither shape matched the allowlist, so both would
fail this guard on every cycle. Extend the allowlist with bugfix and
backport/carry-* (ship lanes already pass via bugfix-v*).
Review of the v3 model found four defects in the new step shells:
- MANUAL_CMDS ended in an unterminated single quote, so bash rejected
  the ENTIRE auto-cut script before it could run (P4 could never succeed).
- the final notice referenced $NEW_lane under set -u (defined var is
  NEW_LANE) — an unbound-variable crash after the push already succeeded.
- the drift warning compared the LANE head against the ship MERGE sha,
  which lives on `bugfix`, never on the lane — it would warn on every
  non-ff ship. Compare against the reviewed lane tip (ship PR head sha,
  threaded as a new resolve output) instead.
- the cycle-close notice printed an empty $VER on publish paths
  (resolve only sets it for cuts); read it from the version step.
#4660)

The epoch-1 transition (reference/release.md) cuts the first v3 lane
from ALIGNED MASTER, whose window from the nearest tag contains ordinary
post-tag master merges — the guard false-alarmed 'lane leak detected'
and its rebuild-from-tag advice would re-inherit the stale pre-v3
workflow file (the self-fire hazard v3 removes). When the lane forked
from master strictly after its base tag, rescan from the fork point.
Simulated all four lane species: tag-cut clean / nested carve-out
unchanged-green, master-cut now green, real master-merge still RED.
…from aligned master)

The issue body states the design but the shipped doc never said how to
get past the one stale artifact left by the incident: tag v0.1.207's
tree carries the v2 wide trigger, and backport.yml auto-cuts a missing
lane from the latest tag on demand. Add the ordered procedure (including
the do-not-label-backport window and advisory bc-2026-001's frozen old
target) plus the two accepted consequences of cutting from aligned
master.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

Review 完成:模型设计成立,但实现里找到 7 个缺陷——已全部修掉并推上 PR 分支(4 个独立标注 commit)。CI 的 test-shard 红是 master 继承性红,与本 PR 无关。

结构化八问:

  1. 是什么问题:本 PR 落地 v3 gate-branch 发布模型——把「任何同仓合入 lane 都触发发布」改成「只有两种形状触发:ship PR(lane→bugfix)发布、alignment PR(bugfix→master)自动切下一 lane」,从根上消灭 [PR] release: arm merge-gated lane publish (lane-side release-bugfix.yml) #4654 事故里「arming commit 自触发」误发 v0.1.207 的那类缺陷。审核确认方向正确,但新代码有 7 个实现层缺陷,其中两个会让流程走不完一个周期。

  2. 什么原因导致的:模型本身没问题(触发形状、双路 resolve、可证明不自触发,均逐条验证过);缺陷在实现层:

    • version-guard 白名单没跟上新的 head 形状:alignment PR(head=bugfix)必然把已发布的版本号带进 master、carry 分支继承 lane pre-bump——两种形状都不在白名单里 → 每个周期的 alignment PR 必红 → 自动切下一 lane 永不触发 → 周期死锁;
    • auto-cut 步骤脚本有一处未闭合的单引号(bash 无法解析整个脚本,P4 永远跑不成功)+ 一处 set -u 下的变量名笔误(push 成功后才崩,假红);
    • 漂移警告拿「lane 头」比「ship merge sha」,而 v3 下 merge sha 只存在于 bugfix、永不在 lane 上 → 每次非 ff 发布都误报一条吓人警告;
    • cycle-close 通知在 publish 路径打出空版本号;
    • lane-leak-guard 仍假设「lane 从 tag 切出」:epoch-1 从对齐后的 master 切第一条 v3 lane 时,master 正常的 post-tag 合并会被误判成「lane 泄漏」,且它的修复建议「从 tag 重建」会重新继承旧 v2 工作流文件(正是自触发风险的来源)——在最要命的时刻给出危险建议;
    • reference/release.md 没写 epoch-1 过渡规程(如何安全跨过「v0.1.207 tag 树还带着 v2 宽触发」这个唯一遗留物)。
  3. 影响范围与严重程度:纯发布管线基建,用户运行时零影响。若不修:第一个 v3 周期会在发布后死锁(alignment PR 红、下一 lane 出不来)、每次发布误报警告、第一条从对齐 master 切的 lane 触发假泄漏告警+危险修复建议。严重度 = 新模型不可用直至修复。

  4. 怎么修复的:4 个独立标注 commit 推到 PR 分支:

    • 843a37fae fix(ci):version-guard 白名单补 bugfix 与 backport/carry-*;
    • e9b8c0541 fix(ci):修 auto-cut/publish 步骤的 4 处 shell 缺陷(引号、笔误、漂移对比对象改为受审 lane 头、版本号填充);
    • 85c9a5ee8 fix(ci):lane-leak-guard 对 master 切出的 lane 改从 fork 点扫描(tag 切出的 lane 行为逐字节不变,四种 lane 模拟验证);
    • a7db582a1 docs(release):补 epoch-1 过渡章节(7 步规程 + 两个被接受的后果 + 被否备选及理由)。
      验证:三个工作流 YAML 解析通过、全部 run block bash -n 通过(引号缺陷即由此捕获)、leak-guard 四型 lane 模拟(干净 tag-cut / 嵌套 carve-out 行为不变、master-cut 转绿、真泄漏仍 RED)、version-guard 模式测试 ALLOW/DENY 符合设计。
  5. 是否有回归问题:逐项审过既有行为——legacy carve-out 路径未动(headsha 为空时回退原对比逻辑);fast dispatch 未动;permissions/secret 面未动;publish sha 语义未变(仍取 ship merge sha;「bugfix 结构上等于 incoming lane 的 base tag」这一前提已写入分析,monotonic npm guard 仍是最后兜底);e2e 触发面未动;tag-cut 与嵌套 carve-out lane 的 leak-guard 行为与之前逐字节一致(模拟证实)。未发现回归。

  6. 是否破坏缓存:不涉及(不触碰缓存/重试/增量游标面)。

  7. 是否改了设计方向:没有——完全按 owner 陈述的设计实现(epoch-1 从对齐 master 切第一条 lane),上述缺陷修完后该设计端到端成立,无需再决策。被否备选(从旧 tag 切 + 中性化 arming carry)已记入 ref.md 并附理由。

  8. 是否引入新配置:没有(无新 env/config/默认值)。

行为变更披露(旧→新):

  • version-guard:白名单新增放行 bugfix、backport/carry-* 两类 head(否则新流程死锁,见第 2 问);
  • 漂移警告:旧行为每次非 ff ship 都告警 → 新行为仅当 lane 真正越过受审 tip 才告警;
  • lane-leak-guard:master 切出 lane 的扫描基线由「最近 tag」改为「fork 点」(其余 lane 类型完全不变);
  • cycle-close 通知:打印真实版本号(此前为空)。

范围扩大披露:除 PR 原有 3 文件外,另改 .github/workflows/lane-leak-guard.yml(+12 行,原因见第 2 问第 5 条)。

CI 状态:新 head a7db582a1 上全部 guard/gate job 绿(version-guard、plan、8× e2e gate、static-gates 等);15 个 test shard 中 8 红——master 继承性红:master head 8b24d1f37 自身同批 shard 红,ci-fixes 哨兵已整体包含于 master(merge 为 no-op),本 PR 只动 workflows+docs。已在 #4599 留一行记录,等 master 侧收敛。

观察项(未修,供参考):

  • 自动开的 alignment PR 正文不带 kernel-change: 标记 → lane 若携带 kernel 变更,kernel-guard 会在 alignment PR 上红(v2 延续的既有模式,也可视为合理的强制函数);
  • path-A 的 glob 略松(bugfix-v[0-9]*.… 能匹配非纯数字段),但版本最终取自 package.json + monotonic guard,风险可忽略;
  • [PR] align master with v0.1.207 (shipped from bugfix-v0.1.206) #4659 当前与 master 冲突,执行 epoch-1 规程第 2 步前需先 rebase。

判定:本 PR 自身门禁面全绿,test-shard 红为继承性(建议等 master 侧收敛后合并;若判断可接受也可直接合并——它是 workflows+docs 变更,不阻塞运行时)。我不能合并(系统规则:合并仅限人工):#4660 。合并后按 reference/release.md 的 Epoch-1 transition 章节执行第 2–7 步即可进入无 arming 循环。

@ranxianglei
ranxianglei merged commit 28b667b into master Oct 25, 2026
46 of 54 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.832-master.28b667b (rolling master tag).

npm install -g billion-context@0.0.832-master.28b667b  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working p2 scope/ci

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant