cloud-connection：runtime config 载荷声明可选的「升级/计费入口」绝对 URL 键（cloud#1850 裁 A 的 framework 半边）

[hotlong]

背景（cloud#1850 裁 A 的 framework 半边；维护者 2026-09-02 在场裁定）

租户运行时的 SPA 在 AI 额度耗尽时给出「升级」入口，但 /api/v1/runtime/config 只下发 cloud 的 origin，没有任何控制面声明的升级/计费页 URL。objectui（objectstack-ai/objectui#7273）已把消费侧改为「只用 origin、不再客户端拼路径；有键则渲染、无键不渲染」。控制面自己两处对这个 URL 的拼法都不一致（billing.ts vs environment-lifecycle.ts），证明消费侧推导不可能稳定。

裁决 A：/api/v1/runtime/config 下发绝对 URL

1. packages/cloud-connection（@objectstack/cloud-connection）在 runtime config 载荷上声明一个可选键，值为控制面升级/计费入口的绝对 URL（命名按该载荷既有键风格，PR 正文说明；缺省不下发）。
2. 类型与（若有）zod/契约测试同步；README/文档中该载荷的字段表加一行。
3. cloud 侧子类填值（cloud#1850 的另一半）在 pin bump 后落地，⛔ 不在本卡做；本卡 PR 正文写明 cloud 侧要填的键名与语义。

契约面

扩大公开载荷 ⇒ Clause-②: yes（契约复审档）。本卡是 epic objectstack-ai/cloud#1841 的 sub-issue。

验收

新键可选、缺省不出现在响应里；类型导出；一条契约测试覆盖「声明了就原样透传、没声明就不出现」；changeset minor。

[hotlong]

Claim: PM loop round 2 (epic objectstack-ai/cloud#1841)
Session: session_c5c0ce54-bb9c-478c-9e5b-cf44b80d4569
Branch: claude/issue-14514-runtime-config-billing-url
Worktree: objectstack-issue-14514
Domain: domain:services
File surface: packages/cloud-connection/** (stop on breach; explain in the report)
Container & model: S/M contract addition, mode:subagent, model: fable (Clause-② content: widens a public payload — dispatch-gates --tier reports no path-derived mandate for this package; the mandate comes from the card CONTENT)
Clause-②: yes
Serial constraints cleared: no open PR touches packages/cloud-connection (checked via open-PR file listing today); objectstack#14371 (plugin-email/auth, enqueued) is disjoint

[hotlong]

Claim: dev
Session: session_c5c0ce54-bb9c-478c-9e5b-cf44b80d4569 (mode:subagent, dispatched by the PM seat of epic objectstack-ai/cloud#1841)
Branch: claude/issue-14514-runtime-config-billing-url (pushed empty at base ed4451219)
Worktree: objectstack-issue-14514
File surface: packages/cloud-connection/** only; no cloud, no objectui, no refactor of the payload's other keys.
Plan: declare one optional absolute-URL key on the runtime config payload beside cloudUrl, export the type, add a contract test (declared = passed through verbatim; undeclared = absent from the response), one row in the package docs field table, minor changeset. GraphQL quota is exhausted on this seat, so all GitHub traffic is REST.

Generated by Claude Code
Clause-②: yes

[hotlong]

os-dev-report

{
  "issue": 14514,
  "status": "done",
  "branch": "claude/issue-14514-runtime-config-billing-url",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/14590",
  "premise_still_valid": true,
  "summary": "Declared an optional top-level `upgradeUrl` (absolute URL of the control plane's upgrade / billing entry) on the /api/v1/runtime/config payload beside `cloudUrl`, filled through a new `upgradeUrl` option on the exported `RuntimeConfigPluginConfig` (host option only, no env var; the cloud subclass fills it after the pin bump). Declared → served verbatim; undeclared or empty → the key is absent (pinned on key presence); not an absolute http(s) URL → refused and named at mount, no key served — so the control plane's current relative `/settings/billing` dialect cannot be forwarded to a tenant origin. README gained a section with a one-row field table (no field table for this payload existed on main), the plugin's Response-shape block gained the row, changeset is minor on @objectstack/cloud-connection, and the PR carries `needs:contract-review` (Clause-② yes; label added via additive REST POST and read back). Premise checks: the payload is assembled AND mounted by RuntimeConfigPlugin itself on the raw Hono app (no objectos-runtime wrapper), no packages/spec schema owns it (spec's RuntimeConfigSchema is the unrelated plugin-security one), so no spec touch. The branch was fast-forwarded onto origin/main 5563bfb32 before the final commit because dispatch-gates flagged the dispatch base 35 commits stale; deps rebuilt after. Assignee was already set (hotlong) at pickup. Not done here by ruling: cloud filling the value, converging cloud's two URL spellings, and the requested evaluation of retiring the relative upgrade_url in env-lifecycle envelopes — all cloud#1850's other half.",
  "tests": "At c0c1f03a7, all locked runs in DECLARED UNLOCKED mode (no flock on macOS; VERDICT lines cite it). Dependency closure build → VERDICT command-exit 0 (rerun after the fast-forward, 81s). Package build → VERDICT command-exit 0, `DTS ⚡️ Build success`, dist/index.d.ts and index.d.cts carry upgradeUrl (6 mentions each), require('./dist/index.cjs') exports RuntimeConfigPlugin. `pnpm --filter @objectstack/cloud-connection exec vitest run --maxWorkers=2` → `Test Files 28 passed (28)`, `Tests 362 passed (362)`, VERDICT command-exit 0. tsc --noEmit -p tsconfig.json --listFiles (package has no typecheck script; a zero-match filter run would have exited 0 having run nothing) → exit 2 with 13 errors, all in three untouched test files (TS2493 x11 + TS2550 x2), byte-for-byte the DEBT ledger's frozen `errors: 13` for this package, so the count does not move; 0 errors in touched files; new test file present in --listFiles (1 hit). Ablation from the committed state: spread replaced by always-present `upgradeUrl: this.upgradeUrl` (marker count 1, spread count 0, blob 8bf0740c vs HEAD 418e09a9) → 11 of 22 red (every key-absence and refusal case; the JSON-round-trip case correctly stayed green since JSON.stringify drops undefined); restore by `git checkout HEAD -- PATH`, hash back to 418e09a9, `git diff HEAD` empty, marker count 0; no dist ablation needed since the suite imports the plugin from source under vitest. check-nul-bytes → `OK (scanned 7923 text file(s) … no raw ASCII control bytes)`; control-byte self-scan of the 4 touched files 0 hits. dispatch-gates --repo objectstack-ai/objectstack (no paths; derived at c0c1f03a7 from 4 files) → 35 families: 31 print their own OK/holds line (incl. check:route-envelope matched on this file, published-files, test-source-alias, type-source-resolution, type-check-coverage, doc-authoring, slot-lookup, logger-receiver-detach, plugin-teardown-shape, adr-0087-registration, changeset-no-major, empty-changeset, objectui-changeset, pm-half-states self-test, keyed-text-bounds, undeclared-dep-imports, comment-mask-adoption, system-context-census, engine-double-contract, objectql-double-limit, query-options-erasure, where-matcher, page-declaration-shape, ci-filter-parity, cross-package-test-inputs x2, shard-attestation, docs-audit affected-docs + drift-comment, release-rehearsal-clone self-test, changeset-gate-self-tests). NOT MEASURED (4), each by the gate's own PREREQUISITE NOT MET exit 3: check-test-completeness (needs a saved turbo test log), pm/check-half-states (anonymous GitHub rate limit exhausted; repo-wide card patrol matched only via the .changeset glob), check:dual-build-cjs-loads and check:type-check-debt --re-measure (need every workspace package built; 35 / 23 have no dist). Declared lint narrowing: eslint --no-inline-config --format json packages/cloud-connection → 43 files, 0 errors, 0 warnings; eslint.config.js enables no type-aware linting (its own comment), so untouched files cannot move.",
  "mcp_calls": "0 — every GitHub read and write went through gh REST (gh api, gh pr create); GraphQL was avoided throughout",
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

[hotlong]

Contract review — PASS (in-seat, contract-review tier; maintainer ruling 2026-08-31 「项目经理是 fable … 可以自己 contract review」). Tier fuse read from this session's harness transcript before review: 676 turns stamped claude-fable-5-1, 0 at a lower tier for the reviewing session.

① Derived judgments (accept-set / public-surface changes in PR #14590):

• New optional top-level key upgradeUrl on the /api/v1/runtime/config payload, beside cloudUrl — additive; absent unless declared; never '' or a guessed default. Correct (matches the cloud#1850 ruling A: published, not derived; consumer already renders no link when absent).
• New host option RuntimeConfigPluginConfig.upgradeUrl (no env var) — the value belongs to the distribution that serves the page; cloud subclass fills it after the pin bump. Correct.
• New refusal: a declared value that is not an absolute http(s) URL (relative path, bare host, other scheme) is refused and named at mount, never forwarded or coerced; empty/whitespace reads as unset. Correct and necessary — a relative /settings/billing would resolve against the tenant origin and recreate the 404 this key removes; loud refusal over silent coercion is the contract-first shape.
• No packages/spec schema owns this payload (spec's RuntimeConfigSchema is the unrelated plugin-security one) — no spec touch, verified by the dev and consistent with the file list.

② Semver: additive optional key + refusal of previously-impossible input ⇒ minor; changeset declares @objectstack/cloud-connection: minor. Consistent.

③ Flags / open questions: none raised. Reach: consumer objectstack-ai/objectui#7273 (merged) already keys on presence; cloud's fill is objectstack-ai/cloud#1850's other half after the pin bump.

Evidence checked against the PR, not the report: 4 files (plugin +108, test +199, README +43, changeset), 28 files / 362 tests green, DTS build success, check-nul-bytes OK, dispatch-gates 31 families OK + 4 PREREQUISITE NOT MET declared; ablation (spread → always-present key) 11/22 red with byte-identical restore. Machine check check-clause2-carriers --pair 14590 → exit 0 after the dual carrier was completed (card label + Clause-②: yes in the dev claim).

Clearing needs:contract-review on both carriers in this stroke; flipping ready; enqueuing when every check is green (CI in progress at review time).

Generated by Claude Code