fix(runtime): AppPlugin contributes its datasource names as a function the set resolves at first read, so init() never walks packages[]

AppPlugin.init()'s manifest registration is the one thing in init() allowed
to touch the artifact's packages[]; resolving the owner list there made a
malformed packages[] refuse from the collections getter too. The host's
code-datasource set now holds deferred contributions, resolved at its first
read (still after every init(), before any reader in start()), and a
contribution that throws stays pending and reaches every reader. Also
restores the space in `const listOf = (`.

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

Author: claude

packages/runtime/src/app-plugin.ts

@@ -159,11 +159,11 @@ export class AppPlugin implements Plugin {
     /** What `grantedPermissions` bound to on this artifact — see {@link ArtifactGrantBinding}. */
     private grantBindingResult?: ArtifactGrantBinding;
     /**
-     * [#21922] {@link codeDefinedDatasourceOwners}, computed once: `init()`
-     * contributes the names to the host's code-datasource set and `start()`
-     * registers the same list, so the two can never disagree about which
-     * datasources this artifact registers from code — and the residual-owner
-     * warning prints once, not once per phase.
+     * [#21922] {@link codeDefinedDatasourceOwners}, computed once: the host's
+     * code-datasource set reads the names through the contribution `init()`
+     * registers, and `start()` registers the same list, so the two can never
+     * disagree about which datasources this artifact registers from code — and
+     * the residual-owner warning prints once, at whichever read comes first.
      */
     private codeDatasourceOwners?: Array<{ datasource: any; owner: { packageId?: string; packageVersion?: string } }>;
     /** When true, init/start become no-ops — env has no app payload. */
@@ -439,10 +439,15 @@ export class AppPlugin implements Plugin {
         // plugin's boot restore — a `start()` — never registers a stored row
         // over one of them, whatever order the plugins were composed in. The
         // in-memory registration itself stays in `start()` (see there).
-        const codeNames = this.codeDefinedDatasourceOwners(ctx)
+        //
+        // Contributed as a FUNCTION the set resolves at its first read, never
+        // resolved here: the names come from `collections`, which walks
+        // `packages[]`, and the manifest registration above is the one thing
+        // in `init()` allowed to touch `packages[]` (#15292's falsifier in
+        // `plugin-dev` pins it). `CodeDatasourceNames` says the rest.
+        contributeCodeDatasourceNames(ctx, () => this.codeDefinedDatasourceOwners(ctx)
             .map(({ datasource }) => datasource?.name)
-            .filter((name): name is string => typeof name === 'string' && name.length > 0);
-        if (codeNames.length > 0) contributeCodeDatasourceNames(ctx, codeNames);
+            .filter((name): name is string => typeof name === 'string' && name.length > 0));
     }
 
     /**
@@ -730,7 +735,7 @@ export class AppPlugin implements Plugin {
         datasource: any;
         owner: { packageId?: string; packageVersion?: string };
     }> {
-        const listOf =(dsDefs: unknown): any[] =>
+        const listOf = (dsDefs: unknown): any[] =>
             Array.isArray(dsDefs)
                 ? dsDefs
                 : dsDefs && typeof dsDefs === 'object'

packages/runtime/src/code-datasource-names.test.ts

@@ -1,21 +1,24 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 //
-// [#21922 / #21944] The host's code-datasource set: one set, filled from code
-// in Phase 1, complete before ANY `start()` runs — which is when the
+// [#21922 / #21944] The host's code-datasource set: one set, contributed to
+// from code in Phase 1, complete before ANY `start()` runs — which is when the
 // datasource-admin plugin's boot restore reads it.
 //
 // The boot case composes its reader FIRST, ahead of every producer. Start
 // order follows insertion where no plugin declares an edge, and none of
 // AppPlugin, DefaultDatasourcePlugin and DatasourceAdminServicePlugin declares
-// one to another — so a set filled in `start()` would be empty here. Filled in
-// `init()`, it is whole.
+// one to another — so a set contributed to in `start()` would be short here.
+// Contributed to in `init()`, it is whole. (AppPlugin's contribution is a
+// function the set resolves at that first read — `CodeDatasourceNames` says
+// why; `plugin-dev`'s #15292 falsifier pins that `init()` itself never reads
+// the artifact's `packages[]` for it.)
 
 import { describe, it, expect } from 'vitest';
 import type { Plugin, PluginContext } from '@objectstack/core';
 import { Runtime } from './runtime.js';
 import { DefaultDatasourcePlugin } from './default-datasource-plugin.js';
 import { AppPlugin } from './app-plugin.js';
-import { CODE_DATASOURCE_NAMES_SERVICE, contributeCodeDatasourceNames } from './code-datasource-names.js';
+import { CODE_DATASOURCE_NAMES_SERVICE, CodeDatasourceNames, contributeCodeDatasourceNames } from './code-datasource-names.js';
 
 // [#10126] Pay the first transform of these dist-resolved workspace deps at MODULE
 // LOAD, not inside a clocked `it()` body (`scripts/check-test-source-alias.mjs`).
@@ -53,13 +56,38 @@ describe('contributeCodeDatasourceNames — one set per kernel', () => {
         contributeCodeDatasourceNames(ctx, ['crm_wh', 'erp_wh']);
 
         expect(registrations()).toBe(1);
-        const set = services.get(CODE_DATASOURCE_NAMES_SERVICE) as Set<string>;
-        expect([...set].sort()).toEqual(['crm_wh', 'default', 'erp_wh']);
+        const set = services.get(CODE_DATASOURCE_NAMES_SERVICE) as CodeDatasourceNames;
+        expect(set.list()).toEqual(['crm_wh', 'default', 'erp_wh']);
+        expect(set.has('crm_wh')).toBe(true);
+        expect(set.has('runtime_wh')).toBe(false);
     });
 
-    it('a name the kernel holds as something other than a set is a composition fault, refused loudly', () => {
+    it('a contribution made as a function is resolved at the first read, not when it is made', () => {
         const { ctx, services } = registryCtx();
-        services.set(CODE_DATASOURCE_NAMES_SERVICE, { has: () => false });
+        let calls = 0;
+
+        contributeCodeDatasourceNames(ctx, () => { calls += 1; return ['app_wh']; });
+        expect(calls).toBe(0);
+
+        const set = services.get(CODE_DATASOURCE_NAMES_SERVICE) as CodeDatasourceNames;
+        expect(set.has('app_wh')).toBe(true);
+        expect(set.has('app_wh')).toBe(true);
+        expect(calls).toBe(1);
+    });
+
+    it('a contribution that throws stays pending and reaches every reader — the set never answers without it', () => {
+        const { ctx, services } = registryCtx();
+        contributeCodeDatasourceNames(ctx, ['default']);
+        contributeCodeDatasourceNames(ctx, () => { throw new Error('the artifact cannot be read'); });
+
+        const set = services.get(CODE_DATASOURCE_NAMES_SERVICE) as CodeDatasourceNames;
+        expect(() => set.has('default')).toThrow(/the artifact cannot be read/);
+        expect(() => set.has('default')).toThrow(/the artifact cannot be read/);
+    });
+
+    it('a name the kernel holds as something other than this set is a composition fault, refused loudly', () => {
+        const { ctx, services } = registryCtx();
+        services.set(CODE_DATASOURCE_NAMES_SERVICE, new Set(['default']));
 
         expect(() => contributeCodeDatasourceNames(ctx, ['default'])).toThrow(/already registered/);
     });
@@ -77,8 +105,7 @@ describe('the host\'s code-datasource set on a booted kernel', () => {
             version: '1.0.0',
             init: async () => {},
             start: async (ctx: PluginContext) => {
-                const set = ctx.getService<Set<string>>(CODE_DATASOURCE_NAMES_SERVICE);
-                seenAtFirstStart = [...set].sort();
+                seenAtFirstStart = ctx.getService<CodeDatasourceNames>(CODE_DATASOURCE_NAMES_SERVICE).list();
             },
         };
 
@@ -94,7 +121,7 @@ describe('the host\'s code-datasource set on a booted kernel', () => {
             await kernel.bootstrap();
             expect(seenAtFirstStart).toEqual(['app_wh', 'default']);
             // One set: the kernel service the two readers resolve by name.
-            expect([...kernel.getService<Set<string>>(CODE_DATASOURCE_NAMES_SERVICE)].sort()).toEqual(['app_wh', 'default']);
+            expect(kernel.getService<CodeDatasourceNames>(CODE_DATASOURCE_NAMES_SERVICE).list()).toEqual(['app_wh', 'default']);
         } finally {
             await kernel.shutdown();
         }
@@ -109,7 +136,7 @@ describe('the host\'s code-datasource set on a booted kernel', () => {
         await kernel.use(new AppPlugin({ manifest: { id: 'com.test.no-ds', name: 'No DS', version: '1.0.0' } }));
         try {
             await kernel.bootstrap();
-            expect([...kernel.getService<Set<string>>(CODE_DATASOURCE_NAMES_SERVICE)]).toEqual(['default']);
+            expect(kernel.getService<CodeDatasourceNames>(CODE_DATASOURCE_NAMES_SERVICE).list()).toEqual(['default']);
         } finally {
             await kernel.shutdown();
         }

packages/runtime/src/code-datasource-names.ts

@@ -3,7 +3,7 @@
 /**
  * The host's code-datasource set (#21922, #21944): the ONE in-memory set of
  * datasource names this host registers from code, kept on the kernel's
- * {@link CODE_DATASOURCE_NAMES_SERVICE} service.
+ * {@link CODE_DATASOURCE_NAMES_SERVICE} service as a {@link CodeDatasourceNames}.
  *
  * ## Who fills it, and when
  *
@@ -12,7 +12,8 @@
  *
  *  - `AppPlugin` — every datasource the installed artifact declares
  *    (`*.datasource.ts`), the same list its `start()` registers in the
- *    MetadataService as `origin: 'code'`;
+ *    MetadataService as `origin: 'code'`, contributed as a function the set
+ *    resolves at its first read ({@link CodeDatasourceNames} says why);
  *  - `DefaultDatasourcePlugin` — the host's own `default`.
  *
  * `init()` is Phase 1, and Phase 1 completes before ANY `start()` runs
@@ -58,35 +59,98 @@
 /** The kernel service the host's code-datasource set is registered under. */
 export const CODE_DATASOURCE_NAMES_SERVICE = 'code-datasource-names';
 
+/**
+ * What a producer contributes: names it knows now, or a function that names
+ * them when the set is first read. `AppPlugin` contributes the function — see
+ * {@link CodeDatasourceNames}.
+ */
+export type CodeDatasourceContribution = Iterable<string> | (() => Iterable<string>);
+
+/**
+ * The set itself. Readers use `has(name)` only, structurally.
+ *
+ * ## Why a contribution can be a function
+ *
+ * `AppPlugin` learns its datasource names from the artifact's `collections`,
+ * and reading `collections` walks `packages[]`, which refuses a malformed entry.
+ * `AppPlugin.init()`'s pinned contract is that its manifest registration is the
+ * ONLY thing in `init()` that touches `packages[]` (#15292's falsifier in
+ * `plugin-dev`): a malformed artifact is refused there, once, and DevPlugin
+ * degrades that refusal to an error line. So `AppPlugin` registers, in
+ * `init()`, a function this set calls at its first read. The CONTRIBUTION is
+ * made in Phase 1 — before any `start()`, which is all the boot restore needs —
+ * and the resolution happens where the set is used (AGENTS.md's first cure for
+ * a startup registry read), with the same list `AppPlugin.start()` registers.
+ *
+ * A contribution that throws stays pending and the throw reaches the reader,
+ * on every read: a set that answered without it would call a code datasource
+ * "not code" without telling anyone.
+ */
+export class CodeDatasourceNames {
+    private readonly names = new Set<string>();
+    private readonly pending: Array<() => Iterable<string>> = [];
+
+    add(contribution: CodeDatasourceContribution): void {
+        if (typeof contribution === 'function') this.pending.push(contribution);
+        else this.addAll(contribution);
+    }
+
+    has(name: string): boolean {
+        this.settle();
+        return this.names.has(name);
+    }
+
+    /** Every name in the set, sorted — for diagnostics and pins. */
+    list(): string[] {
+        this.settle();
+        return [...this.names].sort();
+    }
+
+    private settle(): void {
+        while (this.pending.length > 0) {
+            const resolved = [...this.pending[0]()];
+            this.pending.shift();
+            this.addAll(resolved);
+        }
+    }
+
+    private addAll(names: Iterable<string>): void {
+        for (const name of names) {
+            if (typeof name === 'string' && name.length > 0) this.names.add(name);
+        }
+    }
+}
+
 /** The slice of a plugin context the producers need: the service registry. */
 interface ServiceRegistryContext {
     getService<T>(name: string): T;
     registerService(name: string, service: unknown): void;
 }
 
 /**
- * Add `names` to the host's code-datasource set, registering the set on the
- * kernel the first time any producer contributes. Called from a producer's
+ * Add a contribution to the host's code-datasource set, registering the set on
+ * the kernel the first time any producer contributes. Called from a producer's
  * `init()` only — see the module header for why the phase matters.
  *
  * `getService` throws while the service is unregistered; that miss is the
- * one case that creates the set. A name occupied by something that is not a
+ * one case that creates the set. A name occupied by something that is not this
  * set is a composition fault, and `registerService` throws on it, loudly:
  * failing open there would leave every stored row free to shadow the code
  * definitions this set exists to protect.
  */
-export function contributeCodeDatasourceNames(ctx: ServiceRegistryContext, names: Iterable<string>): void {
+export function contributeCodeDatasourceNames(
+    ctx: ServiceRegistryContext,
+    contribution: CodeDatasourceContribution,
+): void {
     let set: unknown;
     try {
         set = ctx.getService<unknown>(CODE_DATASOURCE_NAMES_SERVICE);
     } catch {
         set = undefined;
     }
-    if (!(set instanceof Set)) {
-        set = new Set<string>();
+    if (!(set instanceof CodeDatasourceNames)) {
+        set = new CodeDatasourceNames();
         ctx.registerService(CODE_DATASOURCE_NAMES_SERVICE, set);
     }
-    for (const name of names) {
-        if (typeof name === 'string' && name.length > 0) (set as Set<string>).add(name);
-    }
+    (set as CodeDatasourceNames).add(contribution);
 }