feat(core): enforce PluginSchema at kernel.use()

`PluginSchema` had zero runtime callers: the boot path checked `name`, `init`
and semver, and every other constraint the protocol declared was a declaration
with nothing behind it. `defineStack` accepted `type: 'ui-plugin'` while
`PluginSchema.safeParse` refused it, and only one of those answers was on the
path a real plugin takes.

`PluginLoader.validatePluginContract` now runs the schema over every plugin
object and refuses one the schema refuses, through the loader's existing error
path with the stable code `PLUGIN_CONTRACT_VIOLATION`, naming the plugin and
the first violated key.

`safeParse` is used for VALIDATION ONLY and the parse output is discarded — a
copy destroys the prototype chain of class-based plugins, which is why
`toPluginMetadata` is a cast. A class-based plugin's identity, prototype and
prototype methods are pinned.

`version` is deliberately excluded and the exclusion is measured, not assumed:
the schema's `/^\d+\.\d+\.\d+$/` refuses the prerelease and build-metadata
forms SemVer 2.0.0 defines, while the loader's own `isValidSemanticVersion`
accepts them and `plugin-loader.test.ts` pins that acceptance deliberately.

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

Author: claude

packages/core/src/plugin-contract-enforcement.test.ts

@@ -0,0 +1,257 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * `kernel.use()` enforces the DECLARED plugin contract (#16049).
+ *
+ * WHY THIS FILE EXISTS. `PluginSchema` (`@objectstack/spec`,
+ * `kernel/plugin.zod.ts`) had zero runtime callers. The boot path ran three
+ * checks — `name`, `init`, semver — and every other constraint the protocol
+ * declared was a declaration with nothing behind it. The sharpest single
+ * reading from #15638, one input and two answers: `defineStack` accepted
+ * `type: 'ui-plugin'` while `PluginSchema.safeParse` refused it, and only one
+ * of those answers was on the path a real plugin takes. The maintainer ruled
+ * enforce, not remove (2026-09-06, ADR-0049): the protocol is the baseline and
+ * the runtime aligns to it.
+ *
+ * WHAT MAKES THE POSITIVE CASES LOAD-BEARING. A file that only asserted
+ * refusals would pass just as well against a `use()` that refused everything.
+ * Every refusal case here has a calibration twin one line away — the SAME
+ * fixture with the offending key corrected — so a refusal is attributable to
+ * the key under test and not to the harness.
+ *
+ * ⭐ THE PROTOTYPE CASE IS NOT A NICETY. The ruling requires `safeParse` be
+ * used for VALIDATION ONLY, because `PluginLoader.toPluginMetadata` is a cast
+ * and its comment records why: "Do not use object spread {...plugin} as it
+ * destroys the prototype chain for Class-based plugins." Substituting the parse
+ * output for the plugin object is the one change that would break every
+ * class-based plugin in the ecosystem while leaving every refusal test in this
+ * file green. Group C is the falsifier for exactly that mistake: it asserts
+ * object IDENTITY, prototype identity, and that a method living only on the
+ * prototype is still callable off what the kernel stored.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { ObjectKernel } from './kernel.js';
+import { PluginLoader } from './plugin-loader.js';
+import { ObjectLogger } from './logger.js';
+import type { Plugin, PluginContext } from './types.js';
+
+/** A kernel that registers plugins and installs no process signal handlers. */
+function makeKernel(): ObjectKernel {
+    return new ObjectKernel({ logger: { level: 'silent' }, gracefulShutdown: false });
+}
+
+/** What `kernel.use()` left in the kernel's own plugin map. */
+function stored(kernel: ObjectKernel, name: string): Record<string, unknown> | undefined {
+    return (kernel as unknown as { plugins: Map<string, Record<string, unknown>> })
+        .plugins.get(name);
+}
+
+/**
+ * A plugin object with an arbitrary extra surface. The keys under test
+ * (`type`, `slug`, `homepage`, `id`) are declared by `PluginSchema` and NOT by
+ * the `Plugin` interface, which is one reason the repo contained no producer of
+ * them — so the fixture states the extra surface rather than casting it away.
+ */
+type Fixture = Plugin & {
+    id?: string;
+    slug?: string;
+    homepage?: string;
+    staticPath?: string;
+};
+
+function fixture(overrides: Partial<Fixture> & { name: string }): Fixture {
+    return {
+        version: '1.0.0',
+        type: 'standard',
+        init: () => { /* a contract fixture registers nothing */ },
+        ...overrides,
+    };
+}
+
+describe('A — the legacy `ui-plugin` value is refused at kernel.use() (#15638, #16049)', () => {
+    it('rejects, and the rejection names the stable code, the plugin and the violated key', async () => {
+        const kernel = makeKernel();
+        const legacy = fixture({
+            name: '@os-fixture/legacy-ui',
+            // The value #15638 MEASURED as accepted, stored verbatim and mounting
+            // routes. It is not a member of `CORE_PLUGIN_TYPES`.
+            type: 'ui-plugin' as unknown as Plugin['type'],
+        });
+
+        await expect(kernel.use(legacy)).rejects.toThrow(/PLUGIN_CONTRACT_VIOLATION/);
+
+        // The envelope, not merely "it threw": a bare `toThrow()` would stay
+        // green if the kernel started refusing this input for an unrelated
+        // reason, which is the failure mode this card was filed about.
+        const err = await kernel.use(legacy).catch((e: unknown) => e as Error);
+        expect(err.message).toContain('PLUGIN_CONTRACT_VIOLATION');
+        expect(err.message).toContain('@os-fixture/legacy-ui');
+        expect(err.message).toContain("at 'type'");
+
+        // …and nothing was stored, so no later seam can read it off the kernel.
+        expect(stored(kernel, '@os-fixture/legacy-ui')).toBeUndefined();
+    });
+
+    it('CALIBRATION — the same fixture with the modern `ui` value loads', async () => {
+        const kernel = makeKernel();
+        const modern = fixture({ name: '@os-fixture/modern-ui', type: 'ui' });
+
+        await expect(kernel.use(modern)).resolves.toBe(kernel);
+        expect(stored(kernel, '@os-fixture/modern-ui')?.type).toBe('ui');
+    });
+
+    it('stamps `code` on the error the loader itself raises', async () => {
+        // `ObjectKernel.use()` re-wraps a failed load into a fresh `Error`
+        // carrying only the message, so the PROPERTY is observable one layer
+        // in. Both surfaces are pinned: the property here, the message above.
+        const loader = new PluginLoader(new ObjectLogger({ level: 'silent' }));
+        const result = await loader.loadPlugin(
+            fixture({ name: 'x', type: 'ui-plugin' as unknown as Plugin['type'] }),
+        );
+
+        expect(result.success).toBe(false);
+        expect((result.error as Error & { code?: string })?.code).toBe('PLUGIN_CONTRACT_VIOLATION');
+    });
+});
+
+describe('B — a plain `standard` plugin still loads', () => {
+    it('registers and is stored verbatim', async () => {
+        const kernel = makeKernel();
+        const plain = fixture({ name: 'com.example.plain' });
+
+        await expect(kernel.use(plain)).resolves.toBe(kernel);
+
+        const entry = stored(kernel, 'com.example.plain');
+        expect(entry).toBeDefined();
+        // Identity, not equality: the loader casts rather than copies, and the
+        // stored entry must be the caller's own object.
+        expect(entry).toBe(plain);
+    });
+
+    it('a plugin declaring NO type at all still loads — `type` is optional', async () => {
+        const kernel = makeKernel();
+        const untyped: Plugin = { name: 'com.example.untyped', version: '1.0.0', init: () => {} };
+
+        await expect(kernel.use(untyped)).resolves.toBe(kernel);
+        // ⛔ The parse output is discarded, so `PluginSchema`'s `.default('standard')`
+        // must NOT have been written back onto the stored object.
+        expect(stored(kernel, 'com.example.untyped')?.type).toBeUndefined();
+    });
+});
+
+describe('C — ⭐ a CLASS-BASED plugin still loads, prototype chain intact', () => {
+    class ClassPlugin implements Plugin {
+        name = 'com.example.class-based';
+        version = '2.3.4';
+        type = 'standard' as const;
+
+        /** Lives on the PROTOTYPE, not on the instance — the whole point. */
+        async init(_ctx: PluginContext): Promise<void> { /* no services */ }
+
+        /** Ditto: unreachable through any copy of the instance. */
+        describeSelf(): string { return `class:${this.name}`; }
+    }
+
+    it('stores the SAME object, with its prototype and prototype methods intact', async () => {
+        const kernel = makeKernel();
+        const instance = new ClassPlugin();
+
+        await expect(kernel.use(instance)).resolves.toBe(kernel);
+
+        const entry = stored(kernel, 'com.example.class-based');
+
+        // The three independent statements a spread would break. Each fails on
+        // its own if `safeParse`'s OUTPUT is ever substituted for the plugin:
+        expect(entry).toBe(instance);                                   // identity
+        expect(Object.getPrototypeOf(entry)).toBe(ClassPlugin.prototype); // chain
+        expect(entry).toBeInstanceOf(ClassPlugin);
+        expect((entry as unknown as ClassPlugin).describeSelf())
+            .toBe('class:com.example.class-based');                      // callable
+
+        // A parse copy carries own enumerable data properties only, so the
+        // control that a spread WOULD have preserved is asserted too — this is
+        // what makes the three above attributable to the prototype and not to a
+        // fixture that happens to have no data.
+        expect(entry?.version).toBe('2.3.4');
+    });
+
+    it('a class-based plugin with a REFUSED type is still refused', async () => {
+        class BadClassPlugin implements Plugin {
+            name = 'com.example.class-bad';
+            version = '1.0.0';
+            type = 'ui-plugin' as unknown as Plugin['type'];
+            async init(): Promise<void> {}
+        }
+
+        const kernel = makeKernel();
+        await expect(kernel.use(new BadClassPlugin())).rejects.toThrow(/PLUGIN_CONTRACT_VIOLATION/);
+    });
+});
+
+describe('D — the other two refusals the changeset states', () => {
+    it('refuses an invalid `slug`', async () => {
+        const kernel = makeKernel();
+        const bad = fixture({ name: '@os-fixture/bad-slug', type: 'ui', slug: 'Not A Slug' });
+
+        const err = await kernel.use(bad).catch((e: unknown) => e as Error);
+        expect(err.message).toContain('PLUGIN_CONTRACT_VIOLATION');
+        expect(err.message).toContain("at 'slug'");
+    });
+
+    it('CALIBRATION — the same fixture with a legal slug loads', async () => {
+        const kernel = makeKernel();
+        const good = fixture({ name: '@os-fixture/good-slug', type: 'ui', slug: 'not-a-slug' });
+
+        await expect(kernel.use(good)).resolves.toBe(kernel);
+    });
+
+    it('refuses an invalid `homepage`', async () => {
+        const kernel = makeKernel();
+        const bad = fixture({ name: '@os-fixture/bad-homepage', homepage: 'not-a-url' });
+
+        const err = await kernel.use(bad).catch((e: unknown) => e as Error);
+        expect(err.message).toContain('PLUGIN_CONTRACT_VIOLATION');
+        expect(err.message).toContain("at 'homepage'");
+    });
+
+    it('CALIBRATION — the same fixture with a real URL loads', async () => {
+        const kernel = makeKernel();
+        const good = fixture({ name: '@os-fixture/good-homepage', homepage: 'https://example.com' });
+
+        await expect(kernel.use(good)).resolves.toBe(kernel);
+    });
+});
+
+describe('E — `version` is DELIBERATELY not enforced from the schema', () => {
+    /**
+     * `PluginSchema.version` is `/^\d+\.\d+\.\d+$/` and refuses the prerelease
+     * and build-metadata forms SemVer 2.0.0 defines, while the loader's own
+     * `isValidSemanticVersion` — the check that has always run — accepts them,
+     * and `plugin-loader.test.ts` pins that acceptance deliberately. Enforcing
+     * the schema's narrower spelling would retire a pinned capability under a
+     * card that ruled on `type`, so the loader's check stays authoritative for
+     * this one key. These cases pin the exclusion so a later change to it is a
+     * decision rather than an accident.
+     */
+    it.each(['1.0.0-alpha.1', '1.0.0+20230101', '0.0.0-fixture'])(
+        'still loads a plugin versioned %s',
+        async (version) => {
+            const kernel = makeKernel();
+            const pre = fixture({ name: `com.example.v-${version}`, version });
+
+            await expect(kernel.use(pre)).resolves.toBe(kernel);
+        },
+    );
+
+    it('and a version the LOADER refuses is still refused, by the loader', async () => {
+        const kernel = makeKernel();
+        const bad = fixture({ name: 'com.example.bad-version', version: 'v1.0.0' });
+
+        // Unchanged message and unchanged owner: this refusal is
+        // `validatePluginStructure`'s, not the contract check's.
+        const err = await kernel.use(bad).catch((e: unknown) => e as Error);
+        expect(err.message).toContain('Invalid semantic version');
+        expect(err.message).not.toContain('PLUGIN_CONTRACT_VIOLATION');
+    });
+});

packages/core/src/plugin-loader.ts

@@ -2,9 +2,27 @@
 
 import { Plugin, PluginContext } from './types.js';
 import type { Logger } from '@objectstack/spec/contracts';
+import { PluginSchema } from '@objectstack/spec/kernel';
 import { parseSignature } from './security/plugin-artifact-signature.js';
 import { serviceNotRegisteredError } from './service-not-registered.js';
 
+/**
+ * The code carried by a refusal raised because the plugin object does not
+ * satisfy `PluginSchema` — the protocol's own declaration of what a plugin
+ * object may be (`@objectstack/spec`, `kernel/plugin.zod.ts`).
+ *
+ * ⚠️ Spelled the ADR-0112 way and deliberately NOT wire vocabulary, exactly
+ * like {@link SERVICE_NOT_REGISTERED_CODE} one module over: this refusal is
+ * raised while the kernel is still assembling itself, before any HTTP boundary
+ * exists, and `dispatcher-error-vocabulary.ts` classifies it `door: 'none'` /
+ * `boot-refusal` for that reason. It is stamped on `err.code` for an in-process
+ * catcher AND repeated at the head of the message, because the message is what
+ * survives: `ObjectKernel.use()` re-wraps a failed load into a fresh `Error`
+ * carrying only `result.error?.message`, so a code that lived only on the
+ * property would not reach the caller that actually sees the boot fail.
+ */
+const PLUGIN_CONTRACT_VIOLATION_CODE = 'PLUGIN_CONTRACT_VIOLATION';
+
 /**
  * Service Lifecycle Types
  * Defines how services are instantiated and managed
@@ -152,6 +170,9 @@ export class PluginLoader {
             // Validate plugin structure
             this.validatePluginStructure(metadata);
 
+            // Validate against the DECLARED contract (#16049)
+            this.validatePluginContract(metadata);
+            
             // Check version compatibility
             const versionCheck = this.checkVersionCompatibility(metadata);
             if (!versionCheck.compatible) {
@@ -389,6 +410,82 @@ export class PluginLoader {
         }
     }
 
+    /**
+     * Refuse a plugin object the DECLARED plugin contract refuses (#16049,
+     * maintainer ruling 2026-09-06: "the protocol is the baseline; the runtime
+     * aligns to it").
+     *
+     * ## What this closes
+     *
+     * `PluginSchema` had **zero runtime callers**. The boot path ran
+     * {@link validatePluginStructure} — `name`, `init`, semver — and nothing
+     * else, so every constraint the protocol declared beyond those three was a
+     * declaration with nothing behind it: `defineStack` accepted a value that
+     * `PluginSchema.safeParse` refused, and the plugin was stored verbatim and
+     * mounted routes. A wrong `type` surfaced (if at all) at route mount; it
+     * now surfaces here, named, at `kernel.use()`.
+     *
+     * ## ⛔ safeParse for VALIDATION ONLY — the parse output is discarded
+     *
+     * The returned object is a COPY, and {@link toPluginMetadata} exists
+     * precisely because a copy "destroys the prototype chain for Class-based
+     * plugins". Substituting the parse output for the plugin would break every
+     * class-based plugin in the ecosystem while leaving this file's own tests
+     * green, so the result is read for `success` and for nothing else.
+     * `plugin-contract-enforcement.test.ts` pins a class-based plugin's
+     * prototype surviving `use()`, which is what makes that a measurement
+     * rather than a promise.
+     *
+     * ## Why `version` is excluded, and why that is not a weakening
+     *
+     * MEASURED on this tree, not assumed. `PluginSchema.version` is
+     * `/^\d+\.\d+\.\d+$/`, which refuses the prerelease and build-metadata
+     * forms SemVer 2.0.0 defines — while {@link isValidSemanticVersion}, the
+     * check this loader has always run, implements the full grammar and accepts
+     * them. Two declarations in this repository disagree about what a version
+     * is, and `plugin-loader.test.ts` pins the wider one deliberately: "should
+     * accept versions with pre-release tags" (`1.0.0-alpha.1`) and "should
+     * accept versions with build metadata" (`1.0.0+20230101`). Two in-repo
+     * class-based plugin fixtures ship `version = '0.0.0-fixture'` and boot
+     * through the real kernel.
+     *
+     * So enforcing the schema's `version` here would not enforce the protocol —
+     * it would RETIRE a pinned capability, silently, under a card that ruled on
+     * `type`. The ruling's own changeset note enumerates what this refuses:
+     * an unknown `type`, an invalid `slug`, an invalid `homepage`. Version is
+     * not in it, and the version check that already runs is the wider, correct
+     * one. Reconciling the two spellings belongs in `packages/spec` beside
+     * #16334; until then this exclusion is declared here rather than performed
+     * by leaving the disagreement unmeasured.
+     */
+    private validatePluginContract(plugin: PluginMetadata): void {
+        const result = PluginSchema.safeParse(plugin);
+        if (result.success) {
+            return;
+        }
+
+        const issues = result.error.issues.filter((issue) => issue.path[0] !== 'version');
+        if (issues.length === 0) {
+            return;
+        }
+
+        // The FIRST issue only: a boot refusal is read by a human reading one
+        // log line, and the first violated key is the one to fix.
+        const first = issues[0];
+        const at = first.path.length > 0 ? first.path.join('.') : '(root)';
+        const id = (plugin as { id?: unknown }).id;
+        const named = typeof id === 'string' && id.length > 0
+            ? `'${plugin.name}' (id: ${id})`
+            : `'${plugin.name}'`;
+
+        const error = new Error(
+            `${PLUGIN_CONTRACT_VIOLATION_CODE}: plugin ${named} is refused by the declared plugin `
+            + `contract at '${at}': ${first.message}`,
+        ) as Error & { code?: string };
+        error.code = PLUGIN_CONTRACT_VIOLATION_CODE;
+        throw error;
+    }
+
     private checkVersionCompatibility(plugin: PluginMetadata): VersionCompatibility {
         // Basic semantic version compatibility check
         // In a real implementation, this would check against kernel version

packages/core/src/types.ts

@@ -124,7 +124,19 @@ export interface Plugin {
      * Plugin type categorisation for runtime behaviour — a {@link PluginType},
      * the closed set the spec declares. The enumeration lives on that type
      * (derived from `CORE_PLUGIN_TYPES`), not in this comment: a value outside
-     * it no longer type-checks, and `PluginSchema.type` refuses it at parse.
+     * it no longer type-checks, and since #16049 `kernel.use()` REFUSES it at
+     * boot — `PluginLoader.validatePluginContract` runs `PluginSchema` over
+     * every plugin object and raises `PLUGIN_CONTRACT_VIOLATION` naming the
+     * plugin and the first violated key.
+     *
+     * ⚠️ This sentence used to say the value was refused "at parse". It was
+     * measured false (#16049, from #15638): `PluginSchema` had no runtime
+     * caller, kernel plugin objects were never parsed, and a `type` outside the
+     * set was accepted and stored verbatim. The refusal this comment describes
+     * is the one that now exists, on the boot path, and the compiler's arm is
+     * the second half rather than the only one — `kernel.use(plugin as any)` is
+     * a shipped in-repo pattern, and externally authored plugins never meet
+     * this compiler at all.
      * @default 'standard'
      */
     type?: PluginType;