From 41c1e310fe0fb33f7042d6151aa63f605c013383 Mon Sep 17 00:00:00 2001 From: awork Date: Fri, 23 Oct 2026 13:47:00 +0800 Subject: [PATCH] docs(dsh): document roster-conditionality of the four Web preset gate rows (#3962) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit dsh.bundle.patch.yml gates four Web presets (preset-standard / preset-ptc / preset-minimal / preset-cordis) on ids that exist only in the FACTORY roster. A profile that replaces them with its own ids matches none of the four rows and dsh logs `patch: entry not found` at startup — buried in the loader logger, surfaced nowhere else. From the outside the rows read as "working" when they are silent no-ops. State the roster-conditionality in the patch file itself (the shipped artifact users inspect): the miss is NOT harmless — an ungated custom preset resolves by import order and may win the race against the overlay middleware register, leaving its compaction-basic AND command-compact rows armed (timing window; worst case a dsh checkpoint outside bili destroys the compression substrate, #3354/#1772/#1729). Mitigation: self-gate each custom preset entry with inject:[biliBasicCompactionPolicy]. Self-check: grep the dsh loader log for `patch: entry ... not found`. Do-not-delete note kept: factory-roster profiles get a real ordering fence from these rows. The launcher overlay carrier (writeDshAcpPatch) mirrors the same clause so the two carriers stay in sync (file's own discipline + #3354 carrier-agreement test). Comments/string-literal only — zero behavior change: no functional patch row is added, removed, or reworded. Rebased onto master after #3729 landed (gate moved to its own always-on bili-compaction-gate entry; structural matching + coverage telemetry shipped there). The four gate rows are unchanged on master, and structural matching widens WHICH entries the transform reaches but not WHEN the middleware registers relative to an ungated preset's resolution — the timing window this note documents persists, so the text needs no rewording. Targeted suites green locally: issue3354-dsh-compaction-disable (incl. two-carriers-agree), issue2605-dsh-retry-patch, issue4147-dsh-overlay-structural (16/16). Full typecheck/test on CI. References #3962 --- dsh.bundle.patch.yml | 26 ++++++++++++++++++++++++++ src/launcher.ts | 2 +- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/dsh.bundle.patch.yml b/dsh.bundle.patch.yml index d7b815f249..c3b2a7a807 100644 --- a/dsh.bundle.patch.yml +++ b/dsh.bundle.patch.yml @@ -29,6 +29,32 @@ # #3354: keep in sync with writeDshAcpPatch in src/launcher.ts — entry inject # lists are REPLACED by patches, not concatenated; if a future dsh ships its # own inject list on these entries, merge manually in BOTH layers. +# #3962: these four gate rows target the FACTORY Web preset roster ONLY. A +# profile that replaces those presets with its own ids has none of them, so all +# four rows match nothing and dsh logs `patch: entry not found` at startup +# (buried in the `loader` logger, surfaced nowhere else). +# +# That miss is NOT harmless — it is a correctness risk. The inject gate is what +# keeps a preset PENDING until the overlay service publishes, i.e. what +# GUARANTEES the global internal/config middleware (src/agent/dsh-compaction- +# disable.ts) registers BEFORE that preset resolves. Per that module's own +# contract the guarantee covers only GATED ("protected") presets; an ungated +# custom preset resolves by import order, which the upstream plugin explicitly +# warns not to rely on. This is a TIMING WINDOW, not a certainty: if such a +# preset happens to resolve before the overlay registers, its compaction-basic +# AND command-compact rows may never be disabled. The direct effect is silent +# misbehavior (the preset loads, but compaction is armed when it should not be); +# the worst case is a dsh compaction checkpoint landing outside bili's knowledge +# and destroying the compression substrate (#3354/#1772/#1729) — which needs +# compaction to actually run. Your own `auto: false` blocks auto-trigger for +# compaction-basic but NOT command-compact. +# +# If your profile uses custom preset ids, SELF-GATE each one by adding +# inject: [biliBasicCompactionPolicy] +# to every custom preset entry (or keep the factory roster). To check whether +# these factory rows applied on YOUR profile, grep the dsh loader log for +# `patch: entry ... not found`. Do NOT delete these rows: factory-roster +# profiles get a real ordering fence from them. - id: preset-standard inject: [biliBasicCompactionPolicy] - id: preset-ptc diff --git a/src/launcher.ts b/src/launcher.ts index 3ae0e8f6d0..f2890780a7 100644 --- a/src/launcher.ts +++ b/src/launcher.ts @@ -3198,7 +3198,7 @@ export function writeDshAcpPatch(dshHome: string, entryName?: string): string | writeOverlayFileAtomic( dir, ".bili-acp.patch.yml", - `- insert:\n - id: bili-native\n name: ${pluginUrl}\n - id: bili-compaction-gate\n name: ${gateUrl}\n- id: compaction-basic\n config:\n auto: false\n# #3354/#3662: keep in sync with dsh.bundle.patch.yml — web-profile presets run their own compaction-basic in nested rows no patch layer can address by id (#1772); these gates make them wait for the load-time overlay the always-on bili-compaction-gate entry registers (vendored from deshark42/dsh-compaction-basic-disable, MIT)\n${compactionDisablePatchRows()}# #2605: keep in sync with dsh.bundle.patch.yml — a patch replaces the row's whole config, so every default code is restated\n- id: llm-deepseek\n config:\n retryPolicy:\n mode: normal\n retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, MALFORMED_RESPONSE]\n- id: llm-deepseek-account\n config:\n retryPolicy:\n mode: normal\n retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, MALFORMED_RESPONSE]\n`, + `- insert:\n - id: bili-native\n name: ${pluginUrl}\n - id: bili-compaction-gate\n name: ${gateUrl}\n- id: compaction-basic\n config:\n auto: false\n# #3354/#3662: keep in sync with dsh.bundle.patch.yml — web-profile presets run their own compaction-basic in nested rows no patch layer can address by id (#1772); these gates make them wait for the load-time overlay the always-on bili-compaction-gate entry registers (vendored from deshark42/dsh-compaction-basic-disable, MIT; #3962: these four target the FACTORY preset roster ONLY — a profile with custom preset ids skips them and those custom presets then have NO ordering fence: the gate is what guarantees the overlay middleware registers before a GATED preset resolves, an ungated custom preset resolves by import order, leaving a TIMING WINDOW where it can resolve first and its compaction-basic AND command-compact rows stay armed (silent misbehavior; worst case substrate destruction #3354/#1772/#1729). Self-gate custom presets with inject:[biliBasicCompactionPolicy]. Full note: dsh.bundle.patch.yml)\n${compactionDisablePatchRows()}# #2605: keep in sync with dsh.bundle.patch.yml — a patch replaces the row's whole config, so every default code is restated\n- id: llm-deepseek\n config:\n retryPolicy:\n mode: normal\n retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, MALFORMED_RESPONSE]\n- id: llm-deepseek-account\n config:\n retryPolicy:\n mode: normal\n retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, MALFORMED_RESPONSE]\n`, ); const file = path.join(dir, ".bili-acp.patch.yml"); try {