From e7ae209302857cbaac6c100552e7ac03b899a1bb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 6 Sep 2026 02:29:52 +0000
Subject: [PATCH] docs(core,rest): the closed-set pins state the durable reason
 `ui-plugin` stays refused
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both `plugin-type-closed-set` pins justified their choice of `'ui-plugin'` by
"the spelling a stale describe() string still uses". No describe string in the
tree uses that spelling any more, so each pin's stated justification read as
expired while the pin itself is still correct and still doing real work — the
failure mode being a later reader who checks the claim, finds nothing, and
deletes a working test as vestigial.

Replaced with the durable reason, identically in both files so the parallel
texts keep explaining the same pinned value the same way: `'ui-plugin'` is the
legacy spelling of today's `'ui'`, callers outside this repo may still send it,
and the closed set must keep refusing it rather than grow a tolerant alias
(Prime Directive #12).

Comment prose only. No assertion, no pinned value and no test semantics change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ARYe3yQTQCUFm5qPYNgKaJ
---
 packages/core/src/plugin-type-closed-set.test.ts     | 6 ++++--
 packages/rest/src/plugin-type-closed-set.pin.test.ts | 6 ++++--
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/packages/core/src/plugin-type-closed-set.test.ts b/packages/core/src/plugin-type-closed-set.test.ts
index d998ad50e4..ef059cb5c7 100644
--- a/packages/core/src/plugin-type-closed-set.test.ts
+++ b/packages/core/src/plugin-type-closed-set.test.ts
@@ -66,8 +66,10 @@ describe('Plugin.type closed set — runtime parity with the spec enum (#13925)'
 
     it('a non-member is refused by PluginSchema with invalid_value at ["type"]', () => {
         // `'plugin'` / `'module'` are PACKAGE manifest types (ManifestSchema.type),
-        // never plugin types; `'ui-plugin'` is the spelling a stale describe()
-        // string still uses; the casing variant guards against a lax comparator.
+        // never plugin types; `'ui-plugin'` is the LEGACY spelling of today's
+        // `'ui'` — once live, so callers outside this repo may still send it, and
+        // the closed set must keep REFUSING it rather than grow a tolerant alias
+        // (Prime Directive #12); the casing variant guards against a lax comparator.
         for (const type of ['bogus', 'ui-plugin', 'plugin', 'module', 'Standard']) {
             const result = PluginSchema.safeParse({ type });
             expect(result.success, `PluginSchema accepted non-member '${type}'`).toBe(false);
diff --git a/packages/rest/src/plugin-type-closed-set.pin.test.ts b/packages/rest/src/plugin-type-closed-set.pin.test.ts
index 6ee1e65ec1..8315856ac8 100644
--- a/packages/rest/src/plugin-type-closed-set.pin.test.ts
+++ b/packages/rest/src/plugin-type-closed-set.pin.test.ts
@@ -67,8 +67,10 @@ describe('Plugin.type closed set — published-surface pins (#13925)', () => {
         const declared: PluginMetadata = {
             name: 'closed-set-pin-metadata',
             version: '1.0.0',
-            // @ts-expect-error — `'ui-plugin'` (a stale describe() spelling) is
-            // not a `PluginType` (#13925).
+            // @ts-expect-error — `'ui-plugin'` is the LEGACY spelling of today's
+            // `'ui'` — once live, so callers outside this repo may still send it,
+            // and the published union must keep REFUSING it rather than grow a
+            // tolerant alias (Prime Directive #12). Not a `PluginType` (#13925).
             type: 'ui-plugin',
             async init() {},
         };