feat(spec): api 补进 DEFAULT_METADATA_TYPE_REGISTRY 与 BUILTIN_METADATA_TYPE_SCHEMAS (#5271)

Part of #5206 (step 1, spec 车道)。

`api` 条目一直被产出(artifact ingest 把 `defineStack({ apis })` 映射为 `api`)、
被索引(`buildEndpointIndex`)、被执行(#5040 E5/E8),而 spec 里哪儿都没声明这个
kind。于是 `getMetadataTypeSchema('api')` 返回 undefined,`saveMetaItem` 走它自己
文档写明的「未注册 schema 的类型不经校验直接落库」分支 —— `PUT /meta/api/:name`
接受任意 JSON。这是 `declared ≠ enforced` 反着读:enforced but undeclared。

- `MetadataTypeSchema` + `DEFAULT_METADATA_TYPE_REGISTRY` 补 `api` 条目;
- `BUILTIN_METADATA_TYPE_SCHEMAS` 补 `api: ApiEndpointSchema`;
- `ApiEndpointSchema` 补 ADR-0010 保护信封(每个注册类型的不变量);
- `api` 的最小 create seed(教 carve-out 形状与 object_operation 的两个半边);
- showcase `KIND_COVERAGE` 接手 `apis` 的覆盖(它不再是「非注册表 kind」)。

旗标按证据定,不是新授权:无静态条目时 `isRuntimeCreateAllowed` 与 `assertAllowed`
都走「无注册表条目 ⇒ 可运行时创建」的兜底(两处注释都点名 `api`),所以运行时直写
本来就被接受、只是不校验。`allowRuntimeCreate: true` 把这个既有判决写下来,
`allowOrgOverride: false` 同样是今天的实际取值。code-only 方案被证据否掉:它会把
今天的 200 变成 403,且 #5086 在落库前对 draft 一视同仁地拒绝,#5206 第 2 步
(PR #5279)将无 draft 可门。

`ApiEndpointSchema` 的收紧被实测否掉:同一个 schema 也解析存量行,而存量行带
`packageId` / `state`,`strictObject` 让 packages/metadata 10 条测试转红。`api` 因此
与 `view` 同列 STILL_STRIP,实测写进该列表注释,真正的修法(信封/正文分离)另立
#5309。

Fixture 逐条裁定而非批量改写:protocol-meta 与 sys-metadata-repository 里的 `api`
标本被**替换**(留着会让断言经另一条分支变绿、却仍宣称在证明「无静态条目」那条);
endpoint-matcher 那条「strips storage annotations」整条重写(它钉的正是信封被丢弃
这个缺陷本身)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ErbEDVAg1No9gdg1pgDAGB

Author: claude

.changeset/api-metadata-type-registry.md

@@ -0,0 +1,80 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `api` is a declared metadata kind — `DEFAULT_METADATA_TYPE_REGISTRY` + `BUILTIN_METADATA_TYPE_SCHEMAS` (#5271, part of #5206)
+
+`api` items were produced, indexed and executed while the spec declared the kind
+nowhere. Artifact ingest maps `defineStack({ apis })` to `api` metadata
+(`ARTIFACT_FIELD_TO_TYPE`), the endpoint matcher indexes them
+(`buildEndpointIndex`), and #5040's executor serves them — but
+`DEFAULT_METADATA_TYPE_REGISTRY` had no `{ type: 'api', … }` entry and
+`BUILTIN_METADATA_TYPE_SCHEMAS` had no `api` binding. So
+`getMetadataTypeSchema('api')` returned `undefined` and `saveMetaItem` took its
+documented "unregistered type is stored without validation" branch:
+`PUT /api/v1/meta/api/:name` accepted **any JSON** and answered 200. That is
+`declared ≠ enforced` read backwards — enforced but **undeclared**.
+
+Both halves are now declared, which is one fix with two faces:
+
+- **A body is validated.** The existing 422 `invalid_metadata` path applies to
+  `api` like every other kind, with structured Zod issues naming the offending
+  key. An endpoint with no `target`, or no `type`, is refused instead of stored.
+- **The type is describable.** `/meta/types` emits a real JSON Schema and a
+  create seed for `api`, so the metadata-admin engine renders a form rather than
+  a raw-JSON textarea, and the entry carries a real label, domain and file
+  patterns instead of the synthesised `label: 'api'`, `filePatterns: []`
+  placeholder a type with no registry row gets.
+
+**The write door is unchanged.** `allowRuntimeCreate: true` records what the
+runtime already did: with no static registry entry, both write gates
+(`isRuntimeCreateAllowed`, `assertAllowed`) fall through to "runtime-creatable",
+and both name `api` in that comment. `allowOrgOverride` stays `false`, also its
+effective value today — an endpoint is the publishing package's outward URL
+contract, and a per-org fork could move `path`, flip `authRequired` or drop
+`rateLimit` on a URL third parties integrate against. Marking the type code-only
+instead (`allowRuntimeCreate: false` + `allowOrgOverride: false`) was considered
+and rejected: it would turn today's 200 into a 403 rather than validate it, and
+#5086's refusal runs before persistence for drafts too, which would leave
+#5206 step 2's `publishPackageDrafts` endpoint gate with no draft to gate.
+
+**`ApiEndpointSchema` gains the ADR-0010 protection envelope, and stays open to
+unknown keys.** Every registered kind must declare the envelope its loader
+stamps (`_packageId` / `_provenance`), or it is dropped on every parse; that
+spread is added. Closing the shape against unknown keys was attempted and
+**measured to be unsafe**: the same schema parses stored rows as well as
+authored declarations (`buildEndpointIndex`, `gateApiItemsForPublish`), and a
+stored row carries the metadata layer's own bookkeeping (`packageId`, `state`),
+so `strictObject` turned 10 tests in `packages/metadata` red — the load-time
+backstop excluded endpoints and the publish gate reported a schema error in
+place of its ADR-0121 D6 verdict. `api` therefore joins `view` on the #4001
+campaign's `STILL_STRIP` list, with that measurement written into the list's own
+note, and the real fix (separating the stored envelope from the body at the
+metadata layer) is filed as #5309 rather than bought by teaching the authoring
+vocabulary two storage keys.
+
+**This is a shape check, not a second servability judge.** ADR-0121's rules —
+the `apps/<namespace>` carve-out (D1/D2), anonymous-requires-an-armed-`rateLimit`
+(D6), the supported target subset, mapping and policy — stay with
+`validateApiEndpointDeclarations` / `identityFreeEndpointGateFailure`, which run
+at publish and again at load. A pin test asserts an anonymous unmetered endpoint
+parses green here and is still refused by the gate, so the two never grow
+competing opinions.
+
+**Upgrade note (not purely additive).** A stored `api` row that does not satisfy
+`ApiEndpointSchema` is refused with 422 on its **next write**; reads and the
+existing load-time behaviour are unchanged (the matcher already excluded
+unparseable rows loudly, #5189). Every `api` declaration reachable in this repo
+— the two E8-migrated showcase endpoints and the two dogfood policy-fixture
+endpoints — was parsed against `ApiEndpointSchema` before landing this: all four
+clean. A live deployment's `sys_metadata` cannot be scanned from CI; an operator
+holding hand-written `api` rows should run `GET /api/v1/meta/diagnostics?type=api`
+(which now covers the type) before upgrading.
+
+ADR-0088's admission test is satisfied on all three clauses: independent
+lifecycle (the matcher indexes and invalidates one item at a time), declarative
+governability (`allowRuntimeCreate` plus file patterns), and a real consumer
+(#5040's executor, boot-proven by #5040 E8). This does not reverse the `router`
+kind's retirement — `router`'s delivered forms are code contributions, whereas a
+single `ApiEndpoint` is a declarative artifact, exactly the "third, real
+delivered form" ADR-0088's own `router` row anticipated.

examples/app-showcase/src/coverage.ts

@@ -115,6 +115,17 @@ export const KIND_COVERAGE: Record<MetadataType, KindCoverage> = {
       'PERMANENT by design (ADR-0088): a runtime-created snapshot produced by Setup → Datasources → Sync (ADR-0062). A package shipping one would be stale on arrival; the showcase demos the federation flow that produces it.',
     issue: ISSUE.noAuthoringSurface,
   },
+  // [#5271] `api` graduated from STACK_COLLECTION_COVERAGE into the registry:
+  // it is now a real metadata kind (`DEFAULT_METADATA_TYPE_REGISTRY` +
+  // `BUILTIN_METADATA_TYPE_SCHEMAS`), so its coverage is owned here. The notes
+  // below moved verbatim from the old `STACK_COLLECTION_COVERAGE.apis` entry —
+  // the proof did not change, only which manifest is responsible for it.
+  api: {
+    status: 'demonstrated',
+    files: ['src/system/apis/index.ts'],
+    notes:
+      'Declarative ApiEndpoint metadata (object_operation + flow targets), MEASURED on a real boot rather than asserted: packages/qa/dogfood/test/showcase-declarative-endpoints.dogfood.test.ts boots the showcase through the artifact-ingestion path and proves each declared path is matched and executed (the find endpoint answers byte-identically to the built-in /data route for the same operation), that `authRequired` denies anonymous with 401, that `cacheTtl: 30` reaches the wire as Cache-Control on successes only, and that /openapi.json and GET /meta/api describe exactly what is mounted. This entry read "demonstrated … executed by the runtime dispatcher (handleApiEndpoint)" once BEFORE that was true — #4936 measured it and found a bare 404 on every declared path, which is why the waiver stood from #4936 until the #5040 executor landed. It is restored to `demonstrated` only because a real-boot test now fails if any of it stops being true (#5040 E8 / #5112). The `router` kind stays retired: code-only (ADR-0088). src/system/server/recalc-endpoint.ts remains the code-mounted HTTP counterpart.',
+  },
   translation: { status: 'demonstrated', files: ['src/system/translations/index.ts'] },
   email_template: { status: 'demonstrated', files: ['src/system/emails/index.ts'] },
   doc: {
@@ -179,12 +190,10 @@ export const STACK_COLLECTION_COVERAGE: Record<string, KindCoverage> = {
     files: ['src/data/extensions/account.extension.ts'],
     notes: 'Merged into showcase_account by the ObjectQL engine at registerApp (priority overlay).',
   },
-  apis: {
-    status: 'demonstrated',
-    files: ['src/system/apis/index.ts'],
-    notes:
-      'Declarative ApiEndpoint metadata (object_operation + flow targets), MEASURED on a real boot rather than asserted: packages/qa/dogfood/test/showcase-declarative-endpoints.dogfood.test.ts boots the showcase through the artifact-ingestion path and proves each declared path is matched and executed (the find endpoint answers byte-identically to the built-in /data route for the same operation), that `authRequired` denies anonymous with 401, that `cacheTtl: 30` reaches the wire as Cache-Control on successes only, and that /openapi.json and GET /meta/api describe exactly what is mounted. This entry read "demonstrated … executed by the runtime dispatcher (handleApiEndpoint)" once BEFORE that was true — #4936 measured it and found a bare 404 on every declared path, which is why the waiver stood from #4936 until the #5040 executor landed. It is restored to `demonstrated` only because a real-boot test now fails if any of it stops being true (#5040 E8 / #5112). The `router` kind stays waived: code-only. src/system/server/recalc-endpoint.ts remains the code-mounted HTTP counterpart.',
-  },
+  // `apis` is NOT listed here any more: as of #5271 it is a registry kind, so
+  // its coverage lives in `KIND_COVERAGE.api` above. Leaving a duplicate row in
+  // this manifest — whose contract is "stack collections that are NOT registry
+  // kinds" — would mean two places to update and one of them silently wrong.
   connectors: {
     status: 'demonstrated',
     files: ['src/system/connectors/index.ts', 'src/automation/flows/index.ts'],

packages/metadata/src/endpoint-matcher.test.ts

@@ -131,14 +131,51 @@ describe('buildEndpointIndex', () => {
     expect(index.get('GET /api/v1/apps/showcase/tasks')!.authRequired).toBe(false);
   });
 
-  it('strips storage annotations (_lock / packageId) rather than choking on them', () => {
+  // [#5271] REPLACED, not re-spelled. This case used to read "strips storage
+  // annotations (_lock / packageId) rather than choking on them" and asserted
+  // `not.toHaveProperty('_lock')` over a fixture spelling `_lock: { managed:
+  // true }` — a shape ADR-0010 never defined (`_lock` is the 4-state enum
+  // none / no-overlay / no-delete / full). Both halves stopped being right when
+  // `api` became a registered kind (#5271, part of #5206):
+  //
+  //  • `ApiEndpointSchema` now declares `...MetadataProtectionFields`, because
+  //    every registered kind must — the loader stamps the envelope and an
+  //    undeclared one is DROPPED on every parse, losing protection metadata on
+  //    round-trip. So the old assertion pinned exactly the defect that spread
+  //    fixes, and it would have kept passing for the wrong reason.
+  //  • The invented `_lock` object is now a VALUE error rather than an unknown
+  //    key, so the endpoint would be excluded from the index entirely — the
+  //    fixture's own premise ("does not choke") silently inverted.
+  //
+  // What remains true, and is what this case now pins: a stored row carries
+  // BOTH the ADR-0010 envelope (declared ⇒ survives) and the metadata layer's
+  // own bookkeeping (`packageId` / `state`, written by `MetadataManager` and
+  // NOT endpoint vocabulary ⇒ stripped). That split is the measured reason
+  // `api` sits on the #4001 campaign's STILL_STRIP list: closing this shape
+  // would make every stored row unparseable here.
+  it('keeps the ADR-0010 envelope and strips the metadata layer’s bookkeeping', () => {
     const index = buildEndpointIndex(
-      [{ ...endpoint(), _lock: { managed: true }, _packageId: 'pkg_showcase' }],
+      [{
+        ...endpoint(),
+        // ADR-0010 envelope — declared by the schema, so it round-trips.
+        _lock: 'no-overlay',
+        _packageId: 'pkg_showcase',
+        _provenance: 'package',
+        // Metadata-layer bookkeeping — not endpoint vocabulary, so stripped.
+        packageId: 'com.objectstack.showcase',
+        state: 'active',
+      }],
       makeLogger(),
     );
-    const hit = index.get('GET /api/v1/apps/showcase/tasks')!;
-    expect(hit).toBeDefined();
-    expect(hit as Record<string, unknown>).not.toHaveProperty('_lock');
+
+    const hit = index.get('GET /api/v1/apps/showcase/tasks');
+    expect(hit, 'a stored row with storage annotations must still index').toBeDefined();
+
+    const body = hit as unknown as Record<string, unknown>;
+    expect(body._packageId).toBe('pkg_showcase');
+    expect(body._lock).toBe('no-overlay');
+    expect(body).not.toHaveProperty('packageId');
+    expect(body).not.toHaveProperty('state');
   });
 });
 

packages/objectql/src/metadata-validation-sweep.test.ts

@@ -13,11 +13,15 @@
  *   2. A deliberately broken payload (missing required field) →
  *      expect `invalid_metadata` + status 422 + structured `issues[]`.
  *
- * Types without a Zod schema in the central registry (`function`,
- * `service`, `router`, plugin-only types like `theme`/`api`/`webhook`) are
- * still expected to pass through unvalidated — that is the documented
- * fall-through, not a regression. We pin it explicitly so any future
- * coverage gap is visible in the report.
+ * Types without a Zod schema in the central registry (plugin-only types like
+ * `theme`/`webhook`) are still expected to pass through unvalidated — that is
+ * the documented fall-through, not a regression. We pin it explicitly so any
+ * future coverage gap is visible in the report.
+ *
+ * [#5271] `api` LEFT that bucket. It was the specimen this paragraph named
+ * while `PUT /meta/api/:name` stored arbitrary JSON (#5206); it is now a
+ * registered kind with `ApiEndpointSchema` bound, so it is swept like any
+ * other runtime-creatable type and has a fixture below.
  */
 
 import { describe, it, expect, vi } from 'vitest';
@@ -193,6 +197,36 @@ const FIXTURES: Record<string, Fixture> = {
         invalid: { apps: { sweep_app: { label: 'Sweep' } } },
         invalidatedField: 'locale',
     },
+    // [#5271, part of #5206] `api` used to sit in this file's "no schema →
+    // fall-through" bucket (see the module doc). It now has one, so it gets a
+    // real fixture: the valid body is the E8-migrated showcase shape (an
+    // `object_operation` endpoint under its stack's ADR-0121 D1 carve-out), and
+    // the invalid body drops `target`, which `ApiEndpointSchema` requires.
+    //
+    // The invalid body is deliberately a SCHEMA violation, not a publish-gate
+    // violation: an off-carve-out path or an anonymous-without-armed-budget
+    // endpoint parses green here and is refused one door later, by
+    // `validateApiEndpointDeclarations` (publish) / `buildEndpointIndex`
+    // (load). This sweep must pin the door it actually is, or it would claim
+    // coverage for a judgement it never makes.
+    api: {
+        valid: {
+            name: 'sweep_task_feed',
+            path: '/api/v1/apps/sweep/tasks',
+            method: 'GET',
+            type: 'object_operation',
+            target: 'sweep_task',
+            objectParams: { object: 'sweep_task', operation: 'find' },
+            authRequired: true,
+        },
+        invalid: {
+            name: 'sweep_task_feed',
+            path: '/api/v1/apps/sweep/tasks',
+            method: 'GET',
+            type: 'object_operation',
+        },
+        invalidatedField: 'target',
+    },
     email_template: {
         valid: {
             name: 'sweep.welcome',