Defer Office background scheduling until a consumer needs it
待调用方需要时再引入 Office 后台调度
The [conversion queue](../../../../packages/document/office-to-pdf/src/queue.ts) implements foreground promotion, demotion after reader cancellation, eviction of queued background work, a reserved foreground reader allowance, and separate background concurrency accounting. These mechanisms protect foreground conversion from speculative prewarming; ordinary conversion still needs the queue's general resource limits. T
English
Problem
The conversion queue implements foreground promotion, demotion after reader cancellation, eviction of queued background work, a reserved foreground reader allowance, and separate background concurrency accounting. These mechanisms protect foreground conversion from speculative prewarming; ordinary conversion still needs the queue's general resource limits.
The Office preview calls its cache without a priority argument, so the Client cache forwards the default foreground priority to the Host. Repository searches for officeToPdf, OfficeToPdfRequest, OfficeToPdfPriority, and maxBackgroundConversions find no production background request. The conversion smoke also submits foreground requests. Background requests appear in queue, Remote, and Client-cache tests. The exposed API and Client priority plumbing alone do not establish which scheduling policy prewarming requires. The open delivery prewarming PR #4064 already provides a concrete prewarming consumer, but its implementation calls the older documentRender API without priority. Removing scheduling must first be reconciled with that consumer; absence from master is insufficient evidence to proceed.
The bounded conversion decision deliberately reserves capacity for foreground consumers. That remains the correct rule if speculation exists, but the current caller inventory does not justify maintaining the speculative request class and its lifecycle interactions.
Proposal
Remove OfficeToPdfPriority, request priority, and configuration maxBackgroundConversions. Remove reader/job priority fields, promotion and demotion, speculative eviction, foreground reader reservation, and the queue's background counter. Remove Client-cache priority plumbing and update the Remote signature together. Admit the oldest queued job whose source reservation fits whenever conversion capacity is available; reject a new distinct job when the metadata queue is full. Continue joining an existing source job subject to the shared reader limit.
Keep the provider, reusable converters, deferred authorized reads, all remaining resource limits, source-version checks, content sharing, bounded result cache, independent reader cancellation, and teardown that waits for actual work to settle. This proposal changes admission policy, not conversion ownership or engine selection.
Update the request/config definitions, package README pair, subsystem and generated catalogs, and conversion fixtures together. Delete priority-only assertions; retain resource and cancellation regressions embedded in mixed priority tests by expressing them with ordinary requests. The existing bounded conversion note remains active because its cache, authorization, and lifetime rationale still applies; acceptance would replace only its scheduling policy.
Alternatives considered
Keep priority for a future prewarm consumer. This avoids a later API change, but retains scheduling states and configuration before a product consumer can define their required behavior. Reintroduce priority with a concrete prewarming caller and measured foreground contention.
Disable background conversions by default. This avoids speculative execution but retains the public request class, configuration, and all scheduling branches.
Remove the whole shared provider or cache. That exceeds the evidence: independent conversion and bounded sharing remain coherent capabilities, and the Loader smoke exercises them without presentation plugins.
Acceptance criteria
- Resolve the scheduling needs of delivery prewarming PR #4064 before implementation, then repeat the caller search. Retain priority if that consumer needs foreground protection; do not remove it merely because the consumer has not merged.
- Priority types, fields, configuration, and scheduling branches disappear from maintained source, tests, documentation, and generated catalogs. Decision records may describe the removed policy.
- Focused queue/provider tests preserve bounded admission, source/digest sharing, cancellation isolation, output ownership, and delayed capacity release. The real conversion Loader smoke still passes.
- Verify the foreground Office preview path; update its recorded-session snapshot if affected. Run the relevant type checks, generated-reference checks, documentation checks, and lint.
Risks
Out-of-tree callers can use the exposed pre-stable API even though repository searches find no background consumer. Removing priority and its config field requires callers to update; this proposal offers no compatibility alias. Speculative callers would lose foreground protection and must stop prewarming until an explicit scheduling requirement is implemented. No runtime behavior changes until this proposal is accepted and implemented.
中文
问题
转换队列 实现了前台优先级提升、读取方取消后的降级、排队后台任务的驱逐、预留前台读取名额，以及独立的后台并发计数。这些机制保护前台转换不受推测性预热影响；普通转换仍需要队列的通用资源限制。
Office 预览 调用缓存时未传优先级，因此Client 缓存 向 Host 转发默认前台优先级。在仓库中搜索 officeToPdf、OfficeToPdfRequest、OfficeToPdfPriority 和 maxBackgroundConversions，未发现生产后台请求。转换冒烟测试 也提交前台请求。后台请求出现在队列、Remote 和 Client 缓存测试中。仅凭暴露 API 和 Client 优先级传递逻辑，无法确定预热需要哪种调度策略。开放的交付文件预热 PR #4064已经提供具体预热消费者，但其实现仍调用不含优先级的旧 documentRender API。删除调度前必须先与该消费者协调；尚未进入 master 不足以支持直接实施。
有界转换决策 有意为前台消费者预留容量。存在推测性任务时，这条规则仍然正确，但当前调用方清单不足以支持维护推测性请求类别及其生命周期交互。
提案
移除 OfficeToPdfPriority、请求中的 priority 和配置 maxBackgroundConversions。删除读取方及任务的优先级字段、升降级、推测性任务驱逐、前台读取名额预留，以及队列的后台计数器。同时删除 Client 缓存的优先级传递逻辑并更新 Remote 签名。在转换容量可用时，接纳源预留容量足够的最早排队任务；元数据队列满时拒绝新的独立任务。仍允许在共享读取方数量限制内加入已有源任务。
保留提供者、可复用转换器、延迟授权读取、其余所有资源限制、源版本校验、内容共享、有界结果缓存、读取方独立取消，以及等待实际工作结束的清理。这项提案改变接纳策略，不改变转换所有权或引擎选择。
同步更新请求及配置定义、包 README 双语文档、子系统与生成目录，以及转换 fixture（测试前置数据）。删除仅针对优先级的断言；将混合优先级测试中的资源与取消回归改写为普通请求，并保留覆盖。现有有界转换记录继续有效，因为其缓存、授权和生命周期理由仍然成立；采纳本提案只会替换其中的调度策略。
考虑过的替代方案
为未来的预热调用方保留优先级。 这可以避免后续 API 变更，但在产品调用方能够定义所需行为之前，就保留了调度状态与配置。应在有具体预热调用方和实测前台资源争用时重新引入优先级。
默认禁用后台转换。 这可以避免推测性执行，但仍保留公开请求类别、配置及全部调度分支。
删除整个共享提供者或缓存。 这超出了证据支持的范围：独立转换和有界共享仍是完整的能力，Loader 冒烟测试也在不依赖展示插件的情况下验证它们。
验收标准
- 实施前先明确交付文件预热 PR #4064 的调度需求，再重复调用方搜索。若该消费者需要前台保护，则保留优先级；不能仅因消费者尚未合入而删除。
- 从维护中的源码、测试、文档和生成目录移除优先级类型、字段、配置及调度分支。决策记录可以描述被移除的策略。
- 聚焦队列及提供者的测试保留有界接纳、源及摘要共享、取消隔离、输出所有权和延迟容量释放覆盖。真实转换的 Loader 冒烟测试仍然通过。
- 验证前台 Office 预览路径；若受影响，同步更新其记录会话快照。运行相关类型检查、生成引用检查、文档检查及 lint。
风险
仓库外调用方可能使用已暴露的稳定前 API，即使仓库搜索未发现后台消费者。移除优先级及其配置字段要求调用方更新；本提案不提供兼容别名。推测性调用方会失去前台保护，必须停止预热，直到明确的调度需求得到实现。本提案被接受并实现之前，运行行为不变。