@@ -0,0 +1,19 @@
+---
+'@objectstack/metadata-protocol': minor
+'@objectstack/runtime': minor
+---
+
+fix(metadata-protocol, runtime)!: a package created at runtime is refused when it carries `navigationContributions`, which its install never registered (#30072)
+
+Clause-②: yes (narrowing) — `POST /api/v1/packages` (both install limbs, its no-protocol fallback included) and the protocol install primitive `installPackage` (and so the package duplicate and every in-process caller) refuse a manifest whose `navigationContributions` is a non-empty list with `400 VALIDATION_ERROR`, a manifest they stored and answered `201` for before. Widened: `@objectstack/metadata-protocol` publishes one new export, `runtimeNavigationContributionsRefusal`, the predicate both doors ask.
+Metadata-protocol: narrowed
+
+<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed or renamed: ManifestSchema.navigationContributions keeps its shape and meaning, and a code package (a defineStack manifest loaded at boot, from the marketplace or by an artifact reload) registers its contributions exactly as before. Only the runtime install door refuses the key, and a refused contribution never reached any app's navigation, so there is no rewrite that keeps what the author meant; the author picks one of the two routes the refusal names. Rows already in sys_packages are data at rest and replay as stored. -->
+
+**BREAKING** accept-set narrowing at the runtime package install door (Studio, REST, MCP and AI authors creating a package at runtime). `os validate`, `os build` and code packages are unchanged.
+
+- **Before.** A package created through `POST /api/v1/packages` with `navigationContributions` targeting another app answered `201` and was stored, but no entry ever appeared in the target app, not after a restart either: only a code package's `registerApp` registers contributions, and neither the install nor the `sys_packages` replay at boot does. Nothing said why.
+- **Now.** The same install is refused `400 VALIDATION_ERROR` before anything is stored, with a sentence that names the key and both routes that work. The refusal is asked ahead of the duplicate-id `409`, so the answer does not depend on whether the id is installed. A manifest with no `navigationContributions`, or an empty list, installs as before.
+- **Not changed.** A code package's contributions (the Setup app's capability plugins, a multi-package artifact's modules, a marketplace package) are registered and served as before. A package already stored with the key keeps loading at boot, and its entries stay unregistered, as they always were.
+
+**What an author does.** To add an entry to an installed app's menu, save an override of that app in its customization package (the app copied with the entry added; Studio's navigation editor writes it). To contribute menu entries into another package's app, ship them in a code package's manifest, which registers them when it loads. Then install the runtime package without `navigationContributions`.
@@ -270,6 +270,12 @@ export { unmanagedInstallPostureRefusal } from './package-unmanaged-install.js';
 // its no-protocol fallback included, instead of keeping a second copy.
 export { customizationPairManifestRefusal } from './protocol-customization-package.js';
 
+// [ADR-0029 D7] The refusal of `navigationContributions` on a package created
+// at runtime, whose install never registers them. The install primitive asks
+// it; exported so `POST /packages` (`@objectstack/runtime`) asks the same one
+// ahead of both its install limbs, its no-protocol fallback included.
+export { runtimeNavigationContributionsRefusal } from './protocol-package-install.js';
+
 // #4556 — the `sys_metadata_history.recorded_by` sentinel → NULL conversion,
 // as an ADR-0119 D2 migration plan. Run by `os migrate recorded-by`.
 export {
 
@@ -39,8 +39,10 @@
  * module cycle is evaluation-safe because the one runtime import is read only
  * inside a function body, never while the two modules are first evaluated.
  * `index.ts` names what it publishes from `protocol.ts` one by one, so the
- * `export` they gained for this keeps them off the published surface, and
- * nothing re-exports this module, so the published surface does not move.
+ * `export` they gained for this keeps them off the published surface. `index.ts`
+ * re-exports one name from this module and nothing else of it:
+ * {@link runtimeNavigationContributionsRefusal}, added after the move, which the
+ * HTTP install door asks ahead of both its limbs.
  */
 
 import type { ObjectStackProtocolImplementation, PackagePersistService } from './protocol.js';
@@ -54,6 +56,45 @@ import { ManifestSchema, deriveNamespaceFromPackageId, manifestIdRefusal } from
 // [ADR-0146 D3] The pair-shaped-id predicate, asked before the namespace default.
 import { customizationPairManifestRefusal } from './protocol-customization-package.js';
 
+/**
+ * [#30072] The refusal of a runtime-created package's `navigationContributions`
+ * (ADR-0029 D7, ADR-0049) — `undefined` when the manifest carries none.
+ *
+ * Navigation contributions are registered by `ObjectQL.registerApp`, the door
+ * a CODE package takes when it loads (boot, marketplace, artifact reload). A
+ * package created at runtime takes this primitive instead, whose registry
+ * write (`SchemaRegistry.installPackage`) registers none of them, and so does
+ * the `sys_packages` replay at the next boot. The key was stored, answered
+ * success and never applied: an author (a person or an AI) was told the menu
+ * entry was added while it never appeared. Maintainer ruling A on the card
+ * (record 6631177389): the runtime door refuses the key loudly, naming the two
+ * routes that work — an override of the app in its customization package for
+ * a customer's own menu (ADR-0146 D2), and a code package for a contribution.
+ *
+ * One predicate for every runtime install door: this primitive asks it, so the
+ * duplicate and every in-process caller are judged; `POST /packages`
+ * (`@objectstack/runtime`) asks it ahead of both its install limbs, its
+ * no-protocol fallback included. An empty array promises nothing and passes.
+ * ⛔ Rows already in `sys_packages` are not judged: they are data at rest and
+ * the boot hydration replays them as stored (the tolerance stated at the
+ * whole-manifest parse below).
+ *
+ * The answer is a request-shape refusal: `400`, whose standard member is
+ * `VALIDATION_ERROR`, with no code minted for it.
+ */
+export function runtimeNavigationContributionsRefusal(manifest: unknown): string | undefined {
+    const contributions = (manifest as { navigationContributions?: unknown } | null | undefined)?.navigationContributions;
+    if (contributions === undefined || (Array.isArray(contributions) && contributions.length === 0)) return undefined;
+    const id = (manifest as { id?: unknown }).id;
+    const named = typeof id === 'string' && id !== '' ? ` '${id}'` : '';
+    return `manifest.navigationContributions is not accepted on a package created at runtime: the package${named} would be `
+        + 'stored with it, but its contributions are never registered, so the menu entries would never appear. '
+        + "To add an entry to an installed app's menu, save an override of that app in its customization package "
+        + '(the app copied with your entry added). To contribute menu entries into another package\'s app, ship '
+        + 'them in a code package, whose navigationContributions are registered when it loads. '
+        + 'Remove navigationContributions from this manifest and retry.';
+}
+
 /**
  * [#21243] Write `manifest` to `sys_packages`, and say whether it failed.
  *
@@ -238,6 +279,16 @@ export async function installPackage(
         );
     }
 
+    // [#30072] A runtime-created package cannot contribute navigation: its
+    // contributions would be stored and never registered. Asked AFTER the
+    // declaration parse, so a malformed manifest keeps the declaration's own
+    // located answer, and before every write and every server-state read
+    // below — a request-shape refusal, the predicate's docblock says why.
+    const navRefusal = runtimeNavigationContributionsRefusal(manifest);
+    if (navRefusal !== undefined) {
+        throw Object.assign(new Error(navRefusal), { statusCode: 400 });
+    }
+
     // [ADR-0146 D3] A paired customization package id (`<base>.custom`) is
     // installed only with what the pair's ensure door writes: the base's pair
     // namespace, explicit, and the dependency on the base. Asked BEFORE the
 
@@ -0,0 +1,92 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#30072] ADR-0029 D7 — the protocol install primitive refuses
+ * `navigationContributions` on a package created at runtime.
+ *
+ * The primitive's registry write (`SchemaRegistry.installPackage`) registers
+ * no contribution, and neither does the `sys_packages` replay at boot: only a
+ * code package's `ObjectQL.registerApp` does. So the key was stored, answered
+ * success and never applied. Every in-process caller passes here (the HTTP
+ * door's composed limb, the duplicate, an embedder), so the gate is on the
+ * primitive.
+ *
+ * Each refusal is pinned by its envelope — what an HTTP boundary answers for
+ * the throw (`resolveThrownHttpError`), status AND code — and by the absence of
+ * both writes. The lit controls hold the other direction.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { resolveThrownHttpError } from '@objectstack/types';
+import { ObjectStackProtocolImplementation } from './protocol.js';
+import { runtimeNavigationContributionsRefusal } from './protocol-package-install.js';
+
+function makeImpl() {
+    const registryCalls: Array<{ manifest: any }> = [];
+    const engine = {
+        registry: {
+            installPackage: (manifest: any) => {
+                registryCalls.push({ manifest });
+                return { manifest, status: 'installed', enabled: true };
+            },
+        },
+        find: async () => [],
+    };
+    const publish = vi.fn(async () => ({ success: true }));
+    const services = new Map<string, any>([['package', { publish }]]);
+    const impl = new ObjectStackProtocolImplementation(engine as never, () => services);
+    return { impl, registryCalls, publish };
+}
+
+/** The thrown refusal, or a failure naming what happened instead. */
+async function refusalOf(run: () => Promise<unknown>): Promise<any> {
+    try {
+        await run();
+    } catch (e) {
+        return e;
+    }
+    throw new Error('expected the call to be refused, but it resolved');
+}
+
+const BASE = { id: 'com.example.leave', name: 'Leave', version: '1.0.0', type: 'module' } as const;
+const CONTRIBUTION = { app: 'crm_app', group: 'group_sales', items: [{ id: 'nav_leave', type: 'object', label: 'Leave', objectName: 'leave_request' }] };
+
+describe('[#30072] installPackage refuses navigationContributions on a runtime-created package', () => {
+    it('refuses a contribution — 400 VALIDATION_ERROR with the prescription, and writes nothing', async () => {
+        const { impl, registryCalls, publish } = makeImpl();
+        const manifest = { ...BASE, navigationContributions: [CONTRIBUTION] };
+        const err = await refusalOf(() => (impl as any).installPackage({ manifest }));
+        expect(resolveThrownHttpError(err)).toMatchObject({ status: 400, code: 'VALIDATION_ERROR' });
+        expect(err.message).toBe(runtimeNavigationContributionsRefusal(manifest));
+        // Neither writer ran: not the in-memory registry, not the durable row.
+        expect(registryCalls).toHaveLength(0);
+        expect(publish).not.toHaveBeenCalled();
+    });
+
+    it('the refusal names the key, the package and both routes that work', () => {
+        const message = runtimeNavigationContributionsRefusal({ ...BASE, navigationContributions: [CONTRIBUTION] });
+        // The sentence is the contract an author (or an AI) repairs from: its
+        // first clause names the key and where it is refused.
+        expect(message?.startsWith('manifest.navigationContributions is not accepted on a package created at runtime')).toBe(true);
+        expect(message).toContain(`'${BASE.id}'`);
+        expect(message).toContain('customization package');
+        expect(message).toContain('code package');
+    });
+
+    it('a malformed manifest keeps the declaration\'s located answer, ahead of this refusal', async () => {
+        const { impl, registryCalls } = makeImpl();
+        const err = await refusalOf(() => (impl as any).installPackage({
+            manifest: { ...BASE, type: 'application', navigationContributions: [CONTRIBUTION] },
+        }));
+        expect(resolveThrownHttpError(err)).toMatchObject({ status: 400, code: 'VALIDATION_ERROR' });
+        expect(err.message).toContain('manifest.type');
+        expect(registryCalls).toHaveLength(0);
+    });
+
+    it('lit control — the same manifest without the key, or with an empty list, installs', async () => {
+        const { impl, registryCalls, publish } = makeImpl();
+        await (impl as any).installPackage({ manifest: { ...BASE } });
+        await (impl as any).installPackage({ manifest: { ...BASE, id: 'com.example.empty', navigationContributions: [] } });
+        expect(registryCalls.map((c) => c.manifest.id)).toEqual([BASE.id, 'com.example.empty']);
+        expect(publish).toHaveBeenCalledTimes(2);
+    });
+});