fix(objectql): the manifest service registers the residual's objects under the stack's manifest id

A multi-package stack's top-level objects that no package body declares are
registered by the metadata door under manifest.id, while the manifest service
read the bodies only, so /meta/object listed them and /data/<name> answered
404 through both boot doors. The service now registers the objects of the
residual rule's own answer (unclaimedTopLevel) after the bodies, under that id,
with no package record of their own.

Claude-Session: https://claude.ai/code/session_01JfJfBUC3cQ6hhgm9MQK76T
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/objectql/src/manifest-service-residual-objects.test.ts

@@ -0,0 +1,191 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * ADR-0130 D4 — the engine's `manifest` service registers the OBJECTS of a
+ * multi-package stack's residual: top-level objects no package body declares,
+ * under the id the residual rule names (`unclaimedTopLevel`,
+ * `@objectstack/metadata`).
+ *
+ * ## The defect these pin
+ *
+ * The metadata door registers a stack's residual under the stack's own
+ * `manifest.id` and the boot warns that every door will report that id as
+ * the items' owner. The `manifest` service read the package BODIES only
+ * (`resolveArtifactPackageOrder` answers `packages[]` when the key is
+ * present), so a residual object never reached the SchemaRegistry: listed by
+ * `GET /meta/object`, `404` on `/data/<name>`, through both boot doors. The
+ * two-boot reading is `packages/cli/test/serve-config-boot-residual.integration.test.ts`
+ * (row 4); these pins hold the engine half on a kernel.
+ *
+ * ## What the shape of each pin is for
+ *
+ *  - The residual object is RESOLVED by the registry and OWNED by the stack's
+ *    manifest id — what the data door reads.
+ *  - CONTROL: the bodies' objects keep their own owners, and no package record
+ *    appears for the residual's id. The residual is not a package; when its id
+ *    names a body (a composed stack keeps one member's manifest) that body's
+ *    record must stay the body's.
+ *  - A late artifact (after `start()`) reaches the metadata service too, and is
+ *    judged against the sealed picklist vocabulary like a body.
+ *
+ * Payloads are handed over the way `AppPlugin` hands them:
+ * `{ ...bundle.manifest, ...bundle }`.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { ObjectKernel } from '@objectstack/core';
+import type { IMetadataService } from '@objectstack/spec/contracts';
+import { ObjectQLPlugin } from './plugin.js';
+import type { ObjectQL } from './engine.js';
+
+type ManifestService = { register(m: unknown): void | Promise<void> };
+
+const engineOf = (kernel: ObjectKernel): ObjectQL => kernel.getService<ObjectQL>('objectql');
+
+const APP_ID = 'com.example.acme';
+const SERVICE_ID = 'com.example.acme.service';
+const RELEASE_ID = 'com.example.acme.release';
+
+const caseObj = () => ({ name: 'acme_case', label: 'Case', sharingModel: 'private', fields: { subject: { type: 'text', label: 'Subject' } } });
+const accountObj = () => ({ name: 'acme_account', label: 'Account', sharingModel: 'private', fields: { name: { type: 'text', label: 'Name' } } });
+const noteObj = (fields: Record<string, unknown> = { title: { type: 'text', label: 'Title' } }) =>
+  ({ name: 'acme_note', label: 'Note', sharingModel: 'private', fields });
+const svc = { id: SERVICE_ID, name: 'service', namespace: 'acme', version: '2.4.0', type: 'module' };
+const app = { id: APP_ID, name: 'acme', namespace: 'acme', version: '1.0.0', type: 'app' };
+
+/** What `AppPlugin.init` hands the `manifest` service. */
+const payload = (bundle: Record<string, unknown>) => ({ ...(bundle.manifest as object), ...bundle });
+
+/** Two packages, a `manifest.id` naming neither, and a top-level `acme_note` no body declares. */
+const residualStack = (note = noteObj()) => payload({
+  manifest: { ...app, id: RELEASE_ID },
+  objects: [caseObj(), accountObj(), note],
+  packages: [
+    { manifest: { ...svc, objects: [caseObj()] } },
+    { manifest: { ...app, objects: [accountObj()] } },
+  ],
+});
+
+const owners = (ql: ObjectQL): Record<string, string | undefined> =>
+  Object.fromEntries(
+    ['acme_account', 'acme_case', 'acme_note'].map((name) => [name, ql.registry.getObjectOwner(name)?.packageId]),
+  );
+
+const acmePackageIds = (ql: ObjectQL): string[] =>
+  ql.registry
+    .getAllPackages()
+    .map((p) => p.manifest?.id)
+    .filter((id: unknown): id is string => typeof id === 'string' && id.startsWith('com.example.'));
+
+let kernel: ObjectKernel | undefined;
+
+async function bootKernel(): Promise<ObjectKernel> {
+  kernel = new ObjectKernel({ logger: { level: 'silent' }, gracefulShutdown: false });
+  await kernel.use(new ObjectQLPlugin());
+  await kernel.bootstrap();
+  return kernel;
+}
+
+afterEach(async () => {
+  if (kernel && kernel.getState() === 'running') await kernel.shutdown();
+  kernel = undefined;
+});
+
+describe('ADR-0130 D4 — the manifest service registers the residual\'s objects', () => {
+  it('registers a residual object under the stack\'s manifest id, beside the bodies\' own', async () => {
+    const k = await bootKernel();
+    await (k.getService('manifest') as ManifestService).register(residualStack());
+    const ql = engineOf(k);
+
+    // Before: `acme_note` resolved to nothing — the data door's 404.
+    expect(ql.registry.resolveObject('acme_note')?.fields?.title).toBeDefined();
+    expect(owners(ql)).toEqual({
+      acme_account: APP_ID,
+      acme_case: SERVICE_ID,
+      acme_note: RELEASE_ID,
+    });
+    expect((ql.registry.resolveObject('acme_note') as { _packageId?: string } | undefined)?._packageId).toBe(RELEASE_ID);
+  });
+
+  it('installs no package record for the residual\'s id — the residual is not a package', async () => {
+    const k = await bootKernel();
+    await (k.getService('manifest') as ManifestService).register(residualStack());
+    expect(acmePackageIds(engineOf(k)).sort()).toEqual([APP_ID, SERVICE_ID]);
+  });
+
+  it('a composed stack whose manifest names a body: the residual takes that id, and the body keeps its own record', async () => {
+    const k = await bootKernel();
+    await (k.getService('manifest') as ManifestService).register(payload({
+      manifest: app,
+      objects: [caseObj(), accountObj(), noteObj()],
+      packages: [
+        { manifest: { ...svc, objects: [caseObj()] } },
+        { manifest: { ...app, objects: [accountObj()] } },
+      ],
+    }));
+    const ql = engineOf(k);
+
+    expect(owners(ql)).toEqual({ acme_account: APP_ID, acme_case: SERVICE_ID, acme_note: APP_ID });
+    // The app body's record is the app body, not the residual: its own
+    // objects, still exactly one.
+    const record = ql.registry.getAllPackages().find((p) => p.manifest?.id === APP_ID);
+    expect((record?.manifest as { objects?: Array<{ name?: string }> } | undefined)?.objects?.map((o) => o.name))
+      .toEqual(['acme_account']);
+  });
+
+  it('CONTROL: a normally composed stack (the top level repeats every body) registers nothing beyond the bodies', async () => {
+    const k = await bootKernel();
+    await (k.getService('manifest') as ManifestService).register(payload({
+      manifest: { ...app, id: RELEASE_ID },
+      objects: [caseObj(), accountObj()],
+      packages: [
+        { manifest: { ...svc, objects: [caseObj()] } },
+        { manifest: { ...app, objects: [accountObj()] } },
+      ],
+    }));
+    const ql = engineOf(k);
+    expect(owners(ql)).toEqual({ acme_account: APP_ID, acme_case: SERVICE_ID, acme_note: undefined });
+    expect(acmePackageIds(ql).sort()).toEqual([APP_ID, SERVICE_ID]);
+  });
+
+  it('`packages: []` beside a top-level object registers the object under the manifest id', async () => {
+    const k = await bootKernel();
+    await (k.getService('manifest') as ManifestService).register(payload({
+      manifest: { ...app, id: RELEASE_ID },
+      objects: [noteObj()],
+      packages: [],
+    }));
+    const ql = engineOf(k);
+    expect(ql.registry.getObjectOwner('acme_note')?.packageId).toBe(RELEASE_ID);
+    expect(acmePackageIds(ql)).toEqual([]);
+  });
+});
+
+describe('ADR-0130 D4 — a residual arriving after start()', () => {
+  it('reaches the metadata service under the stack\'s manifest id, as a body\'s objects do', async () => {
+    const k = await bootKernel();
+    await (k.getService('manifest') as ManifestService).register(residualStack());
+
+    const metadata = k.getService<IMetadataService>('metadata');
+    const bridged = await metadata.getObject('acme_note') as { _packageId?: string } | undefined;
+    expect(bridged?._packageId).toBe(RELEASE_ID);
+  });
+
+  it('is judged against the sealed picklist vocabulary like a body, and a refusal registers nothing', async () => {
+    const k = await bootKernel();
+    const note = noteObj({ status: { type: 'select', label: 'Status', picklist: 'acme_no_such_list' } });
+
+    let caught: (Error & { code?: string; status?: number }) | undefined;
+    try {
+      await (k.getService('manifest') as ManifestService).register(residualStack(note));
+    } catch (e) {
+      caught = e as Error & { code?: string; status?: number };
+    }
+
+    expect(caught?.code).toBe('INVALID_METADATA');
+    expect(caught?.status).toBe(422);
+    expect(caught?.message).toContain('acme_no_such_list');
+    const ql = engineOf(k);
+    expect(owners(ql)).toEqual({ acme_account: undefined, acme_case: undefined, acme_note: undefined });
+  });
+});

packages/objectql/src/plugin.ts

@@ -5,6 +5,10 @@ import { assembleMetadataProtocol } from '@objectstack/metadata-protocol';
 import type { MetadataAuthoringChannel } from '@objectstack/metadata-protocol';
 import { Plugin, PluginContext } from '@objectstack/core';
 import { resolveArtifactPackageOrder, artifactPackageId, readDeploymentOrgScopingEntitlement } from '@objectstack/core';
+// [ADR-0130 D4] The residual rule's decision half — which top-level items of a
+// multi-package stack no body declares, and the id they take. See
+// `unclaimedTopLevelObjects` below.
+import { unclaimedTopLevel } from '@objectstack/metadata';
 import { applyConversionsToStoredItem } from '@objectstack/spec';
 import { StorageNameMapping } from '@objectstack/spec/system';
 // [#21777] The ONE "is this schema the remote's?" predicate, shared with `ObjectQL.syncSchemas`.
@@ -77,6 +81,35 @@ function hasLoadMetaFromDb(service: unknown): service is ProtocolWithDbRestore {
   );
 }
 
+/**
+ * The OBJECTS of a multi-package stack's residual, and the id they are owned
+ * by — the residual rule's own answer (ADR-0130 D4), read through
+ * `unclaimedTopLevel` (`@objectstack/metadata`), the one copy both boot doors
+ * and `os validate` read. ⛔ Never re-derived here: which top-level items are
+ * residual and which id they take is that function's decision, and a second
+ * derivation would let this door and the metadata door disagree about it.
+ *
+ * Why the engine needs them: the `manifest` service registers the BODIES of a
+ * stack that carries `packages[]` and never its top level, while the metadata
+ * door registers the residual under the stack's `manifest.id` and the boot
+ * says every door reports that id as their owner. Without this, a residual
+ * object was listed by `GET /meta/object` and answered `404` on
+ * `/data/<name>`, through both boot doors.
+ *
+ * @returns `undefined` when the stack has no residual object — every stack
+ *   without `packages[]`, and every normally composed one.
+ */
+function unclaimedTopLevelObjects(
+  stack: unknown,
+): { ownerId: string | undefined; objects: ServiceObject[] } | undefined {
+  const residual = unclaimedTopLevel(stack);
+  if (!residual) return undefined;
+  const objects = residual.items
+    .filter((entry) => entry.type === 'object')
+    .map((entry) => entry.item as ServiceObject);
+  return objects.length > 0 ? { ownerId: residual.ownerId, objects } : undefined;
+}
+
 /**
  * [ADR-0131 D6] A `sys_metadata` row stored in a legacy organization's layer:
  * no metadata read serves one, so the authored hook and action binders skip it
@@ -561,8 +594,12 @@ export class ObjectQLPlugin implements Plugin {
       // same one register followed by the same one bridge as before (D7).
       register: (artifact: any) => {
         const ordered = resolveArtifactPackageOrder(artifact) as any[];
+        // [ADR-0130 D4] The objects of the stack's RESIDUAL — top-level objects
+        // no package body declares — as the residual rule answers it. See
+        // {@link unclaimedTopLevelObjects}.
+        const residual = unclaimedTopLevelObjects(artifact);
 
-        if (ordered.length === 0) {
+        if (ordered.length === 0 && residual === undefined) {
           // An artifact that declared `packages: []` registers nothing. Said out
           // loud rather than returning quietly: "the install did nothing" is not
           // a state anyone should have to infer from an absence.
@@ -599,9 +636,11 @@ export class ObjectQLPlugin implements Plugin {
           const declared = new Set<string>();
           for (const manifest of ordered) for (const name of collectManifestPicklistNames(manifest)) declared.add(name);
           const known = (name: string) => declared.has(name) || ql.registry.resolvePicklistOptions(name) !== undefined;
-          const unresolved = ordered
-            .flatMap((manifest) => collectManifestPicklistReferences(manifest, artifactPackageId(manifest)))
-            .filter((ref) => !known(ref.picklist));
+          const unresolved = [
+            ...ordered.flatMap((manifest) => collectManifestPicklistReferences(manifest, artifactPackageId(manifest))),
+            // The residual's objects register below, so they are judged here too.
+            ...(residual ? collectManifestPicklistReferences({ objects: residual.objects }, residual.ownerId) : []),
+          ].filter((ref) => !known(ref.picklist));
           const orphans = ordered
             .flatMap((manifest) => collectManifestPicklistExtensions(manifest, artifactPackageId(manifest)))
             .filter((ext) => !known(ext.picklist));
@@ -615,15 +654,32 @@ export class ObjectQLPlugin implements Plugin {
             id: manifest.id || manifest.name
           });
         }
+        // [ADR-0130 D4] The residual's objects, AFTER every body — the order
+        // the metadata door registers the same stack in — under the id the
+        // residual rule names, through the registry verb a body's own objects
+        // take (`registerApp` step 2), so its refusals are a body's refusals.
+        // There is no package record for that id: the residual is not a
+        // package, and when the id names one of the bodies (a composed stack
+        // keeps one member's manifest) that body's record must not be replaced.
+        if (residual) {
+          for (const object of residual.objects) {
+            ql.registry.registerObject(object, residual.ownerId, undefined, 'own');
+          }
+        }
         // Manifests registered AFTER start() (marketplace install / ledger
         // rehydrate arrive on `kernel:ready` or an HTTP request) land in the
         // SchemaRegistry only — the one-shot startup bridge already ran — so
         // bridge every registered package's objects into the metadata service now.
         // No-op until start() arms it, so boot-time registrations keep the
         // single startup bridge. The promise never rejects; async callers
         // (marketplace install) await it so metadata reads right after
-        // install are deterministic, sync callers may ignore it.
-        return this.bridgeArtifactObjectsToMetadataService(ctx, ordered);
+        // install are deterministic, sync callers may ignore it. The residual's
+        // owner is bridged with them, so a late artifact's residual objects
+        // reach the metadata door as well as the data door.
+        const bridged = residual?.ownerId !== undefined && !scope.packageIds.includes(residual.ownerId)
+          ? [...ordered, { id: residual.ownerId }]
+          : ordered;
+        return this.bridgeArtifactObjectsToMetadataService(ctx, bridged);
       }
     });