fix(spec,core,cloud-connection,metadata): HTTP 契约归一 —— 死影子副本删除,http.server 定为 canonical 并入账 ledger (#4251) (#4393)

* fix(spec,core,cloud-connection,metadata): one HTTP contract, one canonical slot name (#4251)

packages/core/src/contracts/ was a dead near-copy of the real contracts --
zero importers (no relative import, no subpath export, not a tsup entry;
core's barrel has re-exported the spec versions all along) -- and it had
already DIVERGED (spec's IHttpResponse grew write?/end?, IHttpRequest grew
rawBody?; the copy never did). Anyone who grepped into it read a stale
contract nothing enforces -- the both-humans-and-AI failure mode behind
the false http.server exemption (#4382). Deleted; zero-risk by
construction.

`http.server` is the canonical slot name and the ledger now says so:
ServiceSlotContracts gains 'http.server': IHttpServer plus the deprecated
'http-server' alias entry (same instance -- hono-plugin, qa node-plugin
and cloud's two server entrypoints all register both, alias commented
"backward compatibility"). Canonical is the only name on EVERY provider
path -- runtime's config.server path registers no alias, so the three
cloud-connection plugins reading the alias alone found an empty slot
there. All readers now go canonical-first with the alias as a fallback
that dies with the alias registrations; registrations untouched this
release, both sites carry the deprecation note.

getRawApp?(): any joins IHttpServer -- the deliberate framework-handle
escape, declared once with the rationale; four consumers declared it
locally before (cloud-connection x2, metadata HMR, cloud node-server),
and the local RawAppHost / HttpServerWithRawApp types are deleted.

IMetadataService.bulkRegister/bulkUnregister declare the write options
their implementation always accepted (bulkRegister's contract dropped the
MetadataWriteOptions half it intersects in; bulkUnregister declared no
options at all). Same shape as B2's IDataEngine read-methods gap.

Baseline 168 -> 167 (marketplace-install-local's lookup typed while
touched). Ledger test pins both slot entries and the alias equality.

Verified: spec build (dts) + 7192 tests / 281 files; core, metadata,
cloud-connection, plugin-hono-server dts builds; runtime 1001/69, rest
539/36, plugin-auth 579/26, plugin-sharing 226/11, service-settings
196/14, metadata 281/13, hono-server 135/12, http-conformance 46/2;
ratchet holds 167/36 none new; eslint clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(cloud-connection,metadata): the canonical-first read needs a per-name try -- getService throws on an empty slot (#4251)

CI caught the shape my local run could not (I built cloud-connection but ran
only metadata's tests -- cloud-connection's own suites mock a kernel that
registers ONLY the alias): `getService` THROWS for an unregistered slot, so

    try { a = getService('http.server') ?? getService('http-server'); } catch {...}

never reaches the alias -- the first name's throw exits the whole try. Split
into a per-name try (readServer helper) in all four readers.

Worth recording: the pre-existing alias-first read in metadata/plugin.ts had
the SAME shape, so its `?? getService('http.server')` fallback never once
fired either -- a decorative fallback, the declared-vs-actual gap this work
line keeps finding, now actually implemented in both directions.

Verified serially (the earlier 6-file FAIL was local vitest concurrency noise
while spec's dts build ran in parallel -- single-file and serial reruns green):
cloud-connection 64/12, metadata 281/13, both dts builds, eslint clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/http-contract-unification.md

@@ -0,0 +1,54 @@
+---
+"@objectstack/spec": patch
+"@objectstack/core": patch
+"@objectstack/cloud-connection": patch
+"@objectstack/metadata": patch
+"@objectstack/plugin-hono-server": patch
+---
+
+fix(spec,core,cloud-connection,metadata): one HTTP contract, one canonical slot name — and the dead shadow copy that helped cause the false exemption is deleted (#4251)
+
+**`packages/core/src/contracts/` was a dead near-copy of the real contracts,
+and it is gone.** The directory (http-server.ts, data-engine.ts, logger.ts) had
+ZERO importers — no relative import, no subpath export, not a tsup entry;
+core's barrel has re-exported the `@objectstack/spec/contracts` versions all
+along ("Re-export contracts from @objectstack/spec for backward
+compatibility"). But the shadow had already **diverged** from the live
+contract (spec's `IHttpResponse` grew `write?`/`end?` and `IHttpRequest` grew
+`rawBody?`; the copy never did), so anyone who grepped their way into it read a
+stale contract that nothing enforces — the exact both-humans-and-AI failure
+mode behind the false `http.server` exemption (#4382). Deleting it is
+zero-risk by construction: nothing could reach it.
+
+**`http.server` is the canonical slot name, and the ledger now says so.**
+`ServiceSlotContracts` gains `'http.server': IHttpServer` plus the deprecated
+`'http-server'` alias entry (same instance — hono-plugin and qa's node-plugin
+register both two lines apart; cloud's two server entrypoints do the same).
+Canonical is the only name present on EVERY provider path: runtime's
+`config.server` path registers no alias, so the three cloud-connection plugins
+that read the alias alone (marketplace-proxy, runtime-config,
+marketplace-install-local) found an empty slot there — a live miss, now fixed:
+all readers go canonical-first with the alias as a fallback that dies with the
+alias registrations. The registrations themselves are untouched this release;
+both sites now carry the deprecation note.
+
+**`getRawApp?(): any` joins `IHttpServer`** — the deliberate framework-handle
+escape, declared once. Four consumers were each declaring it locally
+(cloud-connection ×2, metadata's HMR routes, cloud's serverless node-server);
+those local `RawAppHost`/`HttpServerWithRawApp` types are deleted. The `any`
+return is deliberate and documented at the single declaration: the handle's
+real type belongs to the framework, and naming it would give the contract a
+framework dependency. Adapters are not required to expose it; consumers
+feature-detect.
+
+**`IMetadataService.bulkRegister`/`bulkUnregister` declare the write options
+their implementation has always accepted.** `bulkRegister`'s contract options
+dropped the `MetadataWriteOptions` half its implementation intersects in
+(`notify` is destructured on the method's first line); `bulkUnregister`
+declared no options at all while the manager takes them. Same shape as the
+`IDataEngine` read-methods gap from B2: a caller typed to the contract could
+not reach the channel without erasing the lookup. Both additive; no implementor
+or caller breaks.
+
+Slot-lookup baseline ratchets 168 → 167 (marketplace-install-local's lookup
+typed while touched).

packages/cloud-connection/src/marketplace-install-local-plugin.ts

@@ -48,6 +48,7 @@ import { resolveMarketplacePublicBaseUrl } from './marketplace-public-url.js';
 import { LocalManifestSource, type InstalledManifestEntry } from './local-manifest-source.js';
 import { ConnectionCredentialStore } from './connection-credential-store.js';
 import { MARKETPLACE_INSTALLED_UI_BUNDLE } from './marketplace-ui.js';
+import type { IHttpServer } from '@objectstack/spec/contracts';
 
 const ROUTE_BASE = '/api/v1/marketplace/install-local';
 
@@ -120,14 +121,20 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
             await this.rehydrate(ctx);
 
             // 2. Mount HTTP endpoints.
-            let httpServer: any;
-            try {
-                httpServer = ctx.getService('http-server');
-            } catch {
+            // [#4251] Read canonical-first with a REAL per-name fallback:
+            // `getService` THROWS for an empty slot, so a single try around
+            // `canonical ?? alias` never reaches the alias — the shape the old
+            // alias-first read had too, meaning its fallback never once fired.
+            const readServer = (name: string): IHttpServer | undefined => {
+                try { return ctx.getService<IHttpServer>(name); } catch { return undefined; }
+            };
+            // Canonical first — see marketplace-proxy-plugin.
+            const httpServer = readServer('http.server') ?? readServer('http-server');
+            if (!httpServer) {
                 ctx.logger?.warn?.('[MarketplaceInstallLocal] http-server not available — install endpoints not mounted');
                 return;
             }
-            if (!httpServer || typeof httpServer.getRawApp !== 'function') {
+            if (typeof httpServer.getRawApp !== 'function') {
                 ctx.logger?.warn?.('[MarketplaceInstallLocal] http-server missing getRawApp() — install endpoints not mounted');
                 return;
             }

packages/cloud-connection/src/marketplace-proxy-plugin.ts

@@ -35,19 +35,6 @@ import {
 
 import type { IHttpServer } from '@objectstack/spec/contracts';
 
-/**
- * The `http-server` slot plus the one member this plugin needs from it.
- *
- * [#4251] `IHttpServer` is a real contract (`@objectstack/spec/contracts`) and
- * this slot is bound to it — but `getRawApp()` is NOT on it, deliberately: the
- * contract is framework-agnostic and the raw app is the framework's own handle
- * (Hono here). So the escape is one named member returning `any`, scoped to the
- * one thing that genuinely cannot be typed framework-agnostically, instead of
- * the whole lookup collapsing to `any`. The probe below is what runs when a
- * host serves the slot with an adapter that exposes no raw app.
- */
-type RawAppHost = IHttpServer & { getRawApp?(): any };
-
 const MARKETPLACE_PREFIX = '/api/v1/marketplace';
 
 /**
@@ -196,14 +183,21 @@ export class MarketplaceProxyPlugin implements Plugin {
                 manifest?.register?.(MARKETPLACE_BROWSE_UI_BUNDLE);
             } catch { /* no manifest service */ }
 
-            let httpServer: RawAppHost | undefined;
-            try {
-                httpServer = ctx.getService<RawAppHost>('http-server');
-            } catch {
+            // [#4251] Read canonical-first with a REAL per-name fallback:
+            // `getService` THROWS for an empty slot, so a single try around
+            // `canonical ?? alias` never reaches the alias — the shape the old
+            // alias-first read had too, meaning its fallback never once fired.
+            const readServer = (name: string): IHttpServer | undefined => {
+                try { return ctx.getService<IHttpServer>(name); } catch { return undefined; }
+            };
+            // `http.server` is canonical (the only name every provider
+            // registers); the alias fallback dies with the alias registrations.
+            const httpServer = readServer('http.server') ?? readServer('http-server');
+            if (!httpServer) {
                 ctx.logger?.warn?.('[MarketplaceProxyPlugin] http-server not available — marketplace routes not mounted');
                 return;
             }
-            if (!httpServer || typeof httpServer.getRawApp !== 'function') {
+            if (typeof httpServer.getRawApp !== 'function') {
                 ctx.logger?.warn?.('[MarketplaceProxyPlugin] http-server missing getRawApp() — marketplace routes not mounted');
                 return;
             }

packages/cloud-connection/src/runtime-config-plugin.ts

@@ -43,19 +43,6 @@ import type { Plugin, PluginContext } from '@objectstack/core';
 import { resolveCloudUrl } from './cloud-url.js';
 import type { IHttpServer } from '@objectstack/spec/contracts';
 
-/**
- * The `http-server` slot plus the one member this plugin needs from it.
- *
- * [#4251] `IHttpServer` is a real contract (`@objectstack/spec/contracts`) and
- * this slot is bound to it — but `getRawApp()` is NOT on it, deliberately: the
- * contract is framework-agnostic and the raw app is the framework's own handle
- * (Hono here). So the escape is one named member returning `any`, scoped to the
- * one thing that genuinely cannot be typed framework-agnostically, instead of
- * the whole lookup collapsing to `any`. The probe below is what runs when a
- * host serves the slot with an adapter that exposes no raw app.
- */
-type RawAppHost = IHttpServer & { getRawApp?(): any };
-
 /**
  * The `env-registry` slot's hostname resolvers — see the call site for both
  * spellings. Async by contract: the consumer awaits the result, and declaring
@@ -196,14 +183,20 @@ export class RuntimeConfigPlugin implements Plugin {
 
     start = async (ctx: PluginContext): Promise<void> => {
         ctx.hook('kernel:ready', async () => {
-            let httpServer: RawAppHost | undefined;
-            try {
-                httpServer = ctx.getService<RawAppHost>('http-server');
-            } catch {
+            // [#4251] Read canonical-first with a REAL per-name fallback:
+            // `getService` THROWS for an empty slot, so a single try around
+            // `canonical ?? alias` never reaches the alias — the shape the old
+            // alias-first read had too, meaning its fallback never once fired.
+            const readServer = (name: string): IHttpServer | undefined => {
+                try { return ctx.getService<IHttpServer>(name); } catch { return undefined; }
+            };
+            // Canonical first — see marketplace-proxy-plugin.
+            const httpServer = readServer('http.server') ?? readServer('http-server');
+            if (!httpServer) {
                 ctx.logger?.warn?.('[RuntimeConfigPlugin] http-server not available — runtime/config not mounted');
                 return;
             }
-            if (!httpServer || typeof httpServer.getRawApp !== 'function') {
+            if (typeof httpServer.getRawApp !== 'function') {
                 ctx.logger?.warn?.('[RuntimeConfigPlugin] http-server missing getRawApp() — runtime/config not mounted');
                 return;
             }