REST routes pay the host kernel-waiter window TWICE per request: resolveRequestEnvironmentId buys a kernel it discards, then resolveProtocol buys it again (42s vs 21s measured)

[os-zhuang]

One REST request on a multi-tenant host pays the host's kernel-waiter window twice: once inside RestServer.resolveRequestEnvironmentId (which asks the ADR-0006 kernel-resolver seam for an environment id and gets a kernel acquisition as a side effect), and again in RestServer.resolveProtocol, which throws the first result away and calls kernelManager.getOrCreate(envId) itself.

Measured on a live deployment

ObjectStack Cloud's KernelManager.waiterTimeoutMs is 20s. Against a wedged environment, same client, within one minute (downstream report: objectstack-ai/cloud#1548):

/health 200 2.23s (static route, no kernel)
/api/v1/health 200 0.92s (host kernel, no tenant kernel)
/api/v1/i18n/locales 503 21.45s ← ONE waiter window (dispatcher-owned route)
/api/v1/metadata 503 22.46s ← ONE waiter window
/api/v1/discovery 503 42.49s ← TWO waiter windows (REST-owned route)
/api/v1/data/sys_user 503 42.71s ← TWO waiter windows (REST-owned route)

The split follows route ownership: the routes that pay once are the runtime dispatcher's; the two that pay twice are the ones @objectstack/rest owns (registerDiscoveryEndpoints — ceded to REST by dispatcher-plugin.ts when both plugins are mounted — and registerCrudEndpoints).

Root cause — one resolution is bought and thrown away

packages/rest/src/rest-api-plugin.ts:187-198 wraps the host's kernel-resolver so the REST server can ask "which environment is this request in?":

async resolveRequestEnvironmentId(req: unknown): Promise<string | undefined> {
 const context: { request: unknown; environmentId?: string } = { request: req };
 await kernelResolver.resolveKernel(context, hostKernelFacade); // ← acquires a KERNEL
 return context.environmentId; // ← keeps only the ID
}

resolveKernel is a kernel-acquisition API. A host implementation resolves the environment, writes context.environmentId, and then awaits the kernel for that environment before returning. The wrapper wants only the id — the kernel it just paid for is discarded on the success path and lost with the rejection on the cold path.

packages/rest/src/rest-server.ts:1057-1069 then swallows the rejection and falls through to the legacy chain:

if (req && this.requestEnvResolver) {
 try {
 return await this.requestEnvResolver.resolveRequestEnvironmentId(req);
 } catch { /* resolver failure → legacy chain */ }
}
// … legacy hostname / X-Environment-Id chain (cached, cheap) …

and resolveProtocol (rest-server.ts:1112-1118) pays for the kernel a second time:

private async resolveProtocol(environmentId?: string, req?: any): Promise<RestProtocol> {
 if (environmentId === 'platform') return this.protocol;
 const envId = await this.resolveRequestEnvironmentId(environmentId, req); // ← window #1
 if (!envId || !this.kernelManager) return this.protocol;
 const kernel = await this.kernelManager.getOrCreate(envId); // ← window #2
 return kernel.getServiceAsync<RestProtocol>('protocol');
}

On a warm environment window #2 is a cache hit and costs nothing, which is why this has been invisible. On a cold or wedged environment each getOrCreate opens its own bounded wait, so one request serially burns two.

The same "resolve the env (→ acquire a kernel), then acquire the kernel again" shape repeats at rest-server.ts lines 934, 971, 1141 and 3107 (resolveEndpointMatchAuthority, resolveMetadataService, resolveI18nService, probeMcpServeable), so routes that reach several of them can stack more than two windows.

Evidence — instrumented, with stacks

Harness: the real RestServer (built packages/rest/dist) wired to a host kernel-resolver implementation and a kernel manager whose build stays in flight, waiterTimeoutMs scaled to 300ms. Every getOrCreate records a stack.

=== GET /api/v1/discovery [GET /api/v1/discovery] ===
 wall time : 768 ms (ONE window = 300 ms)
 windows paid : 2.56 x
 getOrCreate : 2 call(s)
 response : status=503 code=SERVICE_UNAVAILABLE declaredCode=kernel_warming
 --- getOrCreate #1 t+2ms
 at <host>/kernel-resolver.ts (resolveKernel → kernelFor)
 at async _RestServer.resolveRequestEnvironmentId (rest/dist/index.js:57017) ← src rest-server.ts:1067
 at async _RestServer.resolveProtocol (rest/dist/index.js:57052) ← src rest-server.ts:1114
 at async discoveryHandler (rest/dist/index.js:58586) ← src rest-server.ts:3165
 --- getOrCreate #2 t+460ms
 at _RestServer.resolveProtocol (rest/dist/index.js:57054) ← src rest-server.ts:1116
 at async discoveryHandler (rest/dist/index.js:58586)

=== GET /api/v1/data/:object [GET /api/v1/data/:object] ===
 wall time : 605 ms (2.02 x) getOrCreate: 2 call(s) status=503
 --- getOrCreate #1 at rest-server.ts:1067 (via resolveProtocol → list handler, rest-server.ts:6639)
 --- getOrCreate #2 at rest-server.ts:1116

Self-contained framework-only reproduction (no host distribution needed) — a resolver that behaves like a real one, i.e. writes the id and then awaits a kernel:

const NEVER = () => new Promise<any>((r) => setTimeout(r, 60_000));
const km = { getOrCreate: async (_id: string) => { calls++; return boundedWait(NEVER(), 300); } };
const kernelResolver = {
 async resolveKernel(context: any) {
 context.environmentId = 'env_probe'; // resolved BEFORE the kernel is awaited
 return km.getOrCreate('env_probe'); // ← rejects after one 300ms window
 },
};
// wire as rest-api-plugin does, hand RestServer `km` + that requestEnvResolver,
// then invoke the GET /api/v1/data/:object handler and time it.
// observed: ~2 x window, calls === 2

The obvious fix is NOT the fix — also measured

"Swallow the resolver's throw but keep the environmentId it already wrote on the context" removes the legacy-chain detour but changes nothing: measured 2.38x / 2.02x, still 2 getOrCreate calls. The wasted window is spent inside the resolver call, before any id is returned, so no amount of catching at the REST layer reclaims it. The waste is on the success path too — it is simply free there.

Proposed fix — give the seam its own question

The seam asks a kernel-acquisition API an environment-resolution question. Add an environment-only capability to the ADR-0006 contract (KernelResolver, packages/runtime/src/http-dispatcher.ts), have rest-api-plugin's wrapper prefer it, and let resolveProtocol remain the single place that acquires a kernel:

export interface KernelResolver {
 resolveKernel(context, defaultKernel): Promise<ObjectKernel | undefined> | ObjectKernel | undefined;
 /** Resolve ONLY the request's environment onto `context`. No kernel acquisition. */
 resolveEnvironment?(context, defaultKernel): Promise<void> | void;
}

Measured with the resolver's env-resolution chain run kernel-acquisition-free (--envonly in the same harness):

mode	/api/v1/discovery	/api/v1/data/:object	getOrCreate	response
today	768 ms (2.56x)	605 ms (2.02x)	2	503 kernel_warming
catch-and-keep-the-id	714 ms (2.38x)	607 ms (2.02x)	2	503 kernel_warming
resolveEnvironment (proposed)	413 ms (1.38x)	301 ms (1.00x)	1	503 kernel_warming

Two properties the fix must keep, and does:

• Fail closed. The surviving getOrCreate in resolveProtocol still rejects, so a genuinely unavailable kernel is still a 503 — collapsing the windows must not turn "waited 40s then 503" into "served against no kernel". All three rows above answer 503.
• The window itself is untouched. waiterTimeoutMs is a host setting and stays as it is; the defect is waiting twice, not waiting wrong.

An ?.-optional method keeps every existing resolver working unchanged (it just keeps paying twice on cold builds), so this can land before any host implements the new half.

Filed from objectstack-ai/cloud#1548, where the production measurement was taken. The consumer side is deliberately not patched there — the resolution seam and both call sites are framework code.

[os-zhuang]

Maintainer ruling: Option A. 2026-08-22, verbatim:「10988 A，1550 Q1 A」

Adopted: add optional resolveEnvironment?(context, defaultKernel) to the ADR-0006 KernelResolver (packages/runtime/src/http-dispatcher.ts); rest-api-plugin's wrapper prefers it when present; hosts that implement it answer "which environment?" without a kernel acquisition. ?.-optional, so every existing resolver keeps working and the framework half lands before any host implements — no flag day.

Sequencing: framework half first (this card), then the cloud half (implement resolveEnvironment in cloud's kernel-resolver + .objectstack-sha bump) reopens objectstack-ai/cloud#1548, which carries the instrumented probe and the measured target: one waiter window per request, 1.00× on data routes, still failing closed.

Released for dispatch (pm:queue). Note for whichever seat picks it up: this repo had a claim collision on #10825 earlier today — re-read this thread for claims before dispatching.

[huangyiirene]

Triage (re-graded from the filed pm:queue into the decision inbox): the proposed fix adds an optional member (resolveEnvironment?) to the ADR-0006 KernelResolver contract — a cross-repo host-integration interface — and protocol-contract changes sit on the manual floor regardless of how good the evidence is. The evidence here is unusually good, which is why the block below is short.

[facets-block]

• 实际业务需求:生产实测——wedged 环境上 REST 路由 42s×503(两倍 waiter 窗口),cloud#1548 的真实事故读数;修复后 1.00–1.38x,一半延迟直接消失。
• 项目长远合理性:让「问环境」与「买内核」各有其门,消除「买了就扔」的结构性浪费;可选成员向后兼容,旧 resolver 原样工作。
• 防 AI 写代码犯错:catch-and-keep 的「显然修法」已被测量证伪并写卡——正确修法带着否定对照落地,后来者不会再走弯路。
• 创业阶段不扩散需求:一个可选方法,实现方(cloud)就是需求方——有拉动的最小扩面。

一句话问题:KernelResolver 增加可选 resolveEnvironment?(只解析环境、不买内核),让 REST 冷请求从两个 waiter 窗口降到一个?

推荐 A = 采纳(置信度高:三种模式全部实测,fail-closed 保持,waiter 窗口本身不动)。本分析看不见什么:cloud 侧 resolver 实现工作量(应为小,但本席不可测);是否有第三方 host 实现该接口(可选成员使其零负担)。裁决格式:回「A」/「B 不改」。裁后执行:A ⇒ 回 pm:queue 派 cli 席(engine 面协同:rest-api-plugin wrapper 优先新方法 + 卡内点名的另外四个同型调用点同批复核),cloud 侧联动单由验收席立。

---

Generated by Claude Code

[huangyiirene]

Maintainer ruling recorded — A: adopt resolveEnvironment? on the ADR-0006 KernelResolver contract

Provenance: maintainer, 2026-08-22, live session (「同意所有」, item 6 = A).

State: needs-user-decision → pm:queue (cli lane), Task. Scope per the card's own measured proposal: add the optional environment-only capability to the contract; rest-api-plugin's wrapper prefers it; resolveProtocol stays the single kernel-acquisition point; fail-closed preserved (the surviving getOrCreate still 503s on a genuinely unavailable kernel — all three measured modes answered 503 and the fix must keep that); waiterTimeoutMs untouched. The four sibling call sites the card names (resolveEndpointMatchAuthority, resolveMetadataService, resolveI18nService, probeMcpServeable) are re-checked in the same pass. Cross-repo: the cloud-side implementation card is filed by the accepting seat on landing, per the linked-work rule; until cloud implements, existing resolvers keep working (and keep paying twice on cold builds) by design.

---

Generated by Claude Code

[os-elon]

Claim:

• Session: session_019bmVFqoQPq63zhKrxdYG1r (domain:cli lane execution seat, seat post [PM seat] domain:cli — 🟢 os-zhuang (session_019siH5jDmk5hrayvfyojUqR) · R31 · 落地 9 卡 / 8 PR · 入队 1 (#11378) · 在飞 5 · 待复审 1 · 决策箱 2 #6024)
• Branch: claude/issue-10988-kernel-resolver-resolve-environment
• Worktree: ../objectstack-10988 (dedicated, per-task)
• Domain: domain:cli
• File surface (as the ruling scopes it; the dev declares the measured surface in the PR): the ADR-0006 KernelResolver contract in packages/runtime/src/http-dispatcher.ts, the rest-api-plugin wrapper that prefers the new member, and a re-check pass over the four sibling call sites the card names — resolveEndpointMatchAuthority, resolveMetadataService, resolveI18nService, probeMcpServeable.
• Container & model: this container, default tier (opus). Not Clause-① (nothing under .claude/skills/pm-dispatch/**).
• Clause-②: no, expected — the contract lives in packages/runtime, not packages/spec/src/**, and no Clause-② was declared by triage or the maintainer. ⚠️ The dev re-measures the path limb (git diff --name-only origin/main ∩ packages/spec/src/**) and declares the result in the PR; if it fires, the card does not get enqueued at this tier.
• Serial constraints cleared: no open card claims these files. feat(cli): os g skill scaffolds an AI skill as NAME.skill.ts, the name the loader looks for #11054/fix(cli): scaffolded pnpm-workspace.yaml declares an explicit empty packages list #11057 are in packages/cli + packages/create-objectstack and do not overlap.

Re-read of this thread before dispatch, per the note about the #10825 collision: the three comments here are the 03:18Z release, the 13:23Z triage re-grade, and the 13:50Z ruling record. No prior claim by any seat.

Dispatching now.

---

Generated by Claude Code