fix(runtime): refuse a non-array packages in resolveArtifactCollections (#19924)

Fixes #15293

Clause-②: no

<sub>Rewritten short by the `domain:spec#5` seat (2026-09-23T20:02Z).
The dev report is on #15293 (`5801982470`); the earlier long body is in
the edit history.</sub>

Ruling A (`5634034754`): a release artifact's `packages` that is present
but is not an array (`{}`, `0`, `'x'`) is malformed, not absent, and
every reader refuses it. `ObjectStackDefinitionSchema` already declares
`packages: z.array(ArtifactPackageSchema).optional()`, so this narrows
an accept set back to the declaration.

## What changed

- **runtime** (the behaviour change): `resolveArtifactCollections` used
to return the artifact for any non-array `packages`. It now treats only
`undefined` / `null` as absent. Anything else reaches
`resolveArtifactPackageOrder`, which refuses with
`INVALID_ARTIFACT_PACKAGES` (422).
- **spec**: the rule is stated once, beside
`AssembledPackageBodySchema`. The docblocks in core and the two plugin
readers point at it.
- **plugin-security**: its private guard is dropped. Dropping it is
behaviour-equal on the dev's 29-input differential.
- **plugin-dev**: its private guard is kept, and the reason is written
at the site. Dropping it turns an existing pin red.
- **Pins**: `{}`, `0` and `'x'` at all three call sites, with lit
controls. Reverting the runtime line turns the three runtime pins red.
- **changeset**: `@objectstack/runtime` patch.

## Not in this PR

- The `@objectstack/cli` readers still return nothing for a non-array
`packages`: #19925.
- `packages: null` is refused by the schema but read as absent by every
reader: #19926.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01Sfe5YjBLwB9J3y8fvm2xq1

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/15293-non-array-packages-refusal.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/runtime": patch
+---
+
+A release artifact whose `packages` is present but is not an array (`{}`, `0`, `'x'`) is now refused by the runtime's collection reader too, as `INVALID_ARTIFACT_PACKAGES` (ADR-0112, `status: 422`) (#15293).
+
+Clause-②: no
+
+`packages` is declared as an array of package entries (`ObjectStackDefinitionSchema.packages: z.array(ArtifactPackageSchema).optional()`), and the rule is now written down once, beside `AssembledPackageBodySchema` in `@objectstack/spec`: an absent `packages` means a single-package artifact, and any other non-array value is malformed and refused. `resolveArtifactPackageOrder` in `@objectstack/core` already refused it, and so did the i18n detector in `@objectstack/plugin-dev` and the default-permission-set reader in `@objectstack/plugin-security`.
+
+- **What changes**: `AppPlugin` reads its collections in `start()`, and `start()` now raises the same refusal `init()` already raised through the kernel's `manifest` service. Under `os dev`, `DevPlugin`'s child-`start()` loop logs it on its `error` line, where before the app started on its top-level collections alone. `createStandaloneStack` now refuses such an artifact while it builds the stack. Before, the refusal came later, when the app registered with the `manifest` service. `loadArtifactBundle`'s runtime-module merge reports it through its existing `warn` line and skips the merge, as it already does for a malformed `packages[]` entry. `resolveProjectDatabaseUrl` no longer reads a default datasource out of such an artifact: it declines, as it already does for any artifact it cannot read, and moves on to the next rung (the unified default database). The boot that loads the artifact then refuses it.
+- **What does not change**: an absent `packages`, and `packages: null`, still return the caller's own object by identity. A well-formed `packages[]` resolves exactly as before.
+- **Fix**: remove the `packages` key for a single-package artifact, or make it an array of `{ manifest: … }` entries.

content/docs/plugins/packages.mdx

@@ -400,6 +400,9 @@ metadata it names.
   one step later, when the app's own `init()` hands the stack to the kernel's
   `manifest` service and its package list is parsed; it reports as
   `INVALID_ARTIFACT_PACKAGE_ENTRY` (422) on the `error` line naming the app plugin.
+  A `packages` value that is not an array at all, such as `{}`, takes the same
+  branch and reports as `INVALID_ARTIFACT_PACKAGES` (422). It is malformed, not
+  absent: for a single-package app, leave the key out.
 
   The two differ at the production doors as well. The malformed `packages[]` fails
   the protocol schema, so both `os validate` and `os build` exit 1 on it. The missing

packages/core/src/artifact-packages.ts

@@ -34,6 +34,10 @@
  * - `packages` present → iterate it.
  * - `packages` absent  → treat `manifest` (singular) as a **single-element list**.
  *
+ * A `packages` that is present but is not an array takes neither branch. It is
+ * refused here as `INVALID_ARTIFACT_PACKAGES`. The rule is stated once,
+ * beside `AssembledPackageBodySchema` (`@objectstack/spec`, `stack.zod.ts`).
+ *
  * The second branch is not a convenience: it is the term ADR-0130's whole
  * compatibility claim rests on (D7 — an existing single-`manifest` artifact must
  * register bit-identically through this path). That is why this function returns
@@ -188,8 +192,11 @@ interface ArtifactPackageNode extends OrderablePlugin {
  * @param artifact - A release artifact (`{ packages: [...] }`), or a bare
  *   manifest / single-`manifest` artifact — both shapes are read.
  * @returns The manifest bodies to register, in the order to register them.
- * @throws An ADR-0112 envelope (`code` + `status: 422`) for a malformed entry or
- *   a duplicate package id, and `resolvePluginOrder`'s own error for a cycle.
+ * @throws An ADR-0112 envelope (`code` + `status: 422`):
+ *   `INVALID_ARTIFACT_PACKAGES` for a `packages` that is present but is not an
+ *   array, `INVALID_ARTIFACT_PACKAGE_ENTRY` for a malformed entry, and
+ *   `DUPLICATE_ARTIFACT_PACKAGE` for a duplicate package id. Also
+ *   `resolvePluginOrder`'s own error for a cycle.
  */
 export function resolveArtifactPackageOrder(artifact: unknown): unknown[] {
   const declared = (artifact as { packages?: unknown } | null | undefined)?.packages;
@@ -200,6 +207,8 @@ export function resolveArtifactPackageOrder(artifact: unknown): unknown[] {
   // built to date takes, and D7 pins that it did not move.
   if (declared === undefined || declared === null) return [artifact];
 
+  // Present but not an array: malformed, never absent. The rule is stated
+  // once, beside `AssembledPackageBodySchema`.
   if (!Array.isArray(declared)) {
     throw refuse(
       'INVALID_ARTIFACT_PACKAGES',

packages/plugins/plugin-dev/src/dev-i18n-packages-reader.test.ts

@@ -340,6 +340,46 @@ describe('#15232 — DevPlugin i18n auto-detect over a multi-package stack', ()
     expect(caught?.message).toContain('packages[0]');
   });
 
+  // A `packages` that is present but is not an array is MALFORMED, not absent
+  // (the rule beside `AssembledPackageBodySchema`). This reader's private guard
+  // may decide only the absent branch, so these three reach the resolver.
+  const refusalOf = (stack: unknown): (Error & { code?: string; status?: number }) | undefined => {
+    try {
+      devI18nPluginOptions(stack);
+      return undefined;
+    } catch (err) {
+      return err as Error & { code?: string; status?: number };
+    }
+  };
+
+  it.each([
+    ['{}', {}],
+    ['0', 0],
+    ["'x'", 'x'],
+  ])('`packages: %s` is REFUSED with INVALID_ARTIFACT_PACKAGES, never read as absent', (_label, packages) => {
+    // No `i18n` config and no top-level `translations`, so the question
+    // reaches the package pass. See the next case for a stack that never does.
+    const caught = refusalOf({ manifest: { id: CORE_ID, name: 'x', version: '1.0.0', type: 'app' }, packages });
+    expect(caught?.code).toBe('INVALID_ARTIFACT_PACKAGES');
+    expect(caught?.status).toBe(422);
+  });
+
+  it('lit controls for the rows above: a well-formed `packages[]` resolves, and an absent key takes the single-package branch', () => {
+    // Without these, an instrument that always threw would pin the three rows
+    // above just as green.
+    expect(refusalOf(optionBProject())).toBeUndefined();
+    expect(devI18nPluginOptions(optionBProject())).toEqual({ defaultLocale: undefined, fallbackLocale: 'en' });
+
+    // Absent, explicitly `undefined`, and `null`: the guard's one decision.
+    const manifest = { id: CORE_ID, name: 'x', version: '1.0.0', type: 'app' };
+    for (const absent of [{}, { packages: undefined }, { packages: null }]) {
+      expect(refusalOf({ manifest, ...absent })).toBeUndefined();
+      expect(devI18nPluginOptions({ manifest, ...absent })).toBeUndefined();
+      expect(devI18nPluginOptions({ manifest, ...absent, translations: [{ en: {} }] }))
+        .toEqual({ defaultLocale: undefined, fallbackLocale: 'en' });
+    }
+  });
+
   // ── What the developer actually gets: the SERVICE ─────────────────────────
 
   const bootWith = async (stack: Record<string, unknown> | undefined) => {

packages/plugins/plugin-dev/src/dev-i18n.ts

@@ -95,6 +95,26 @@ const declaresTranslationArray = (body: unknown): boolean => {
  * read the top-level `translations` a second time — the same answer, reached
  * twice, for every single-package stack the platform has ever emitted.
  *
+ * ## Why this reader KEEPS a private guard, and what the guard may not decide
+ *
+ * The rule for which `packages` values are absent and which are refused is
+ * stated once, beside `AssembledPackageBodySchema` (`@objectstack/spec`,
+ * `stack.zod.ts`). `resolveArtifactPackageOrder` is where it is enforced. A
+ * reader should not spell it a second time, and the security reader's twin of
+ * this guard was dropped for that reason. This one stays, deliberately, because
+ * dropping it was measured NOT to be behaviour-equal here. Its answer and its
+ * refusals do not move, but a single-package stack then reads its
+ * `translations` twice instead of once. The pin "a single-package stack reads
+ * its `translations` ONCE" (`dev-i18n-packages-reader.test.ts`) holds this
+ * reader to exactly the old path, and it goes red without the guard.
+ *
+ * ⛔ So the guard is allowed to decide ONE thing: the ABSENT branch, spelled
+ * exactly as the resolver's own absent branch (`undefined` / `null`). Every
+ * other value goes to the resolver, so a present non-array `packages` (`{}`,
+ * `0`, `'x'`) is REFUSED as `INVALID_ARTIFACT_PACKAGES`. ⛔ Never widen it to
+ * `Array.isArray`: that is the silent fall-through the rule above forbids. If
+ * the resolver's absent branch ever changes, this line changes with it.
+ *
  * ## A malformed `packages[]` is refused, not skipped
  *
  * A non-array `packages`, an entry inlined instead of wrapped under `manifest:`
@@ -120,17 +140,11 @@ const declaresTranslationArray = (body: unknown): boolean => {
  * maintainer question filed separately; it is not decided here, and this
  * function's own semantics are unchanged by it.
  *
- * ## The guard divergence with `@objectstack/core`, recorded rather than fixed
- *
- * This reader treats only an ABSENT `packages` key (`undefined` / `null`) as
- * "single package"; anything else goes to the gate, so `packages: {}` is
- * REFUSED. `resolveArtifactPackageOrder`'s own second branch is spelled
- * `declared === undefined || declared === null` too, but the sibling reader in
- * `@objectstack/metadata` guards with `Array.isArray`, which silently accepts a
- * non-array. Two readers in one program answering the same input differently is
- * a program-level split, not this file's to settle (#15226 spells it as this
- * file does). Recorded here so the next author does not "fix" one side into
- * agreement without ruling the other.
+ * ⚠️ The refusal is reached only when the question reaches the package pass. A
+ * stack whose top-level `translations` already answers `true` returns before
+ * the walk, so its `packages` is never read here, malformed or not. That is the
+ * top-level-first order above, and it is deliberate: this reader refuses what
+ * it READS. Such a stack is refused by the load path instead.
  *
  * ## `i18n` is NOT read from `packages[]`, and that is not an omission
  *

packages/plugins/plugin-security/src/app-default-permission-set.test.ts

@@ -339,12 +339,36 @@ describe('appSecurityPluginOptions over `packages[]` (ADR-0130 D4, #15007)', ()
       }
     };
 
-    it('`packages` that is not an array', () => {
-      const err = refusalOf({ packages: 'nope' });
+    // A `packages` that is present but is not an array is MALFORMED, not absent
+    // (the rule beside `AssembledPackageBodySchema`). This reader keeps no
+    // `packages` guard of its own, so the refusal is the resolver's.
+    it.each([
+      ['{}', {}],
+      ['0', 0],
+      ["'x'", 'x'],
+    ])('`packages: %s`, which is not an array', (_label, packages) => {
+      const err = refusalOf({ packages });
       expect(err.code).toBe('INVALID_ARTIFACT_PACKAGES');
       expect(err.status).toBe(422);
     });
 
+    it('lit controls for the rows above: a well-formed `packages[]` resolves, and an absent key takes the single-package branch', () => {
+      // Without these, an instrument that always threw would pin the three
+      // rows above just as green.
+      const wellFormed = { manifest: { id: CORE_ID, name: 'Core', version: '1.0.0', type: 'app', permissions: [permissionSet(CORE_PROFILE)] } };
+      expect(refusalOf({ packages: [wellFormed] })).toEqual({});
+      expect(appSecurityPluginOptions({ packages: [wellFormed] })).toEqual({ fallbackPermissionSet: CORE_PROFILE });
+
+      // Absent, explicitly `undefined`, and `null`: all three read the top level
+      // exactly as before the private guard was dropped.
+      for (const absent of [{}, { packages: undefined }, { packages: null }]) {
+        expect(refusalOf({ ...absent, permissions: [permissionSet('top')] })).toEqual({});
+        expect(appSecurityPluginOptions({ ...absent, permissions: [permissionSet('top')] }))
+          .toEqual({ fallbackPermissionSet: 'top' });
+        expect(appSecurityPluginOptions({ ...absent })).toBeUndefined();
+      }
+    });
+
     it('an entry inlined instead of wrapped under `manifest:`', () => {
       const err = refusalOf({ packages: [{ id: CORE_ID, name: 'Core', version: '1.0.0', type: 'app', permissions: [permissionSet(CORE_PROFILE)] }] });
       expect(err.code).toBe('INVALID_ARTIFACT_PACKAGE_ENTRY');

packages/plugins/plugin-security/src/app-default-permission-set.ts

@@ -169,18 +169,25 @@ export function appDefaultPermissionSetName(permissions: unknown): string | unde
  * loadable or refused, and which answer this reader gives about it must not
  * depend on whether its flattened level happened to name a default first.
  *
+ * ⛔ This reader has no `packages` guard of its own. Which `packages` values
+ * are absent and which are refused is answered by `resolveArtifactPackageOrder`
+ * alone. The rule is stated once, beside `AssembledPackageBodySchema`
+ * (`@objectstack/spec`, `stack.zod.ts`). A private `undefined` / `null` check
+ * here would be a second spelling of that answer.
+ *
  * ## One thing it deliberately does NOT do
  *
  * It does not look inside the SINGULAR `manifest`. That constraint is #7001's
  * and it still holds — the harness must not honour a declaration `serve.ts`
- * ignores. Note this is not a special case bolted on: an artifact carrying no
- * `packages` key never reaches the package pass at all, so that branch reads
- * `permissions` from exactly where the old code read it and nowhere else.
+ * ignores. Note this is not a special case bolted on. When the artifact carries
+ * no `packages` key, D4's second branch hands back the artifact ITSELF as the
+ * one package body. So the package pass re-reads `permissions` from exactly
+ * where the flattened read did, the top level, and nowhere else. That re-read
+ * cannot change the answer, because the flattened read already returned
+ * `undefined` for the same value.
  */
 function declaredDefaultPermissionSetName(config: unknown): string | undefined {
-  const packages = (config as { packages?: unknown } | null | undefined)?.packages;
-  const bodies =
-    packages === undefined || packages === null ? [] : resolveArtifactPackageOrder(config);
+  const bodies = resolveArtifactPackageOrder(config);
 
   const flattened = (config as { permissions?: unknown } | null | undefined)?.permissions;
   const fromFlattened = appDefaultPermissionSetName(flattened);

packages/runtime/src/artifact-collections.test.ts

@@ -80,7 +80,7 @@ describe('packageOwnedCollectionKeys', () => {
 });
 
 describe('resolveArtifactCollections', () => {
-    it('returns the ARGUMENT ITSELF for anything without `packages[]`', () => {
+    it('returns the ARGUMENT ITSELF for a non-object and for an ABSENT `packages`', () => {
         // The D7 branch: every single-package artifact and every `defineStack()`
         // config the platform has ever booted takes it, and identity is the only
         // way to say "this cannot have moved" rather than to hope so.
@@ -89,10 +89,45 @@ describe('resolveArtifactCollections', () => {
         expect(resolveArtifactCollections(null)).toBe(null);
         expect(resolveArtifactCollections(undefined)).toBe(undefined);
         expect(resolveArtifactCollections('not an object')).toBe('not an object');
-        // `packages` present but not an array is not a shape this walks; the
-        // artifact's own loader refuses it.
-        const odd = { packages: 'nope', objects: [obj('o')] };
-        expect(resolveArtifactCollections(odd)).toBe(odd);
+        // An explicit `undefined`, and `null`, read as absent too. `null` is read
+        // this way by every reader today; the schema's `.optional()` refuses it,
+        // and that disagreement is recorded beside `AssembledPackageBodySchema`
+        // rather than decided here.
+        const explicitUndefined = { packages: undefined, objects: [obj('o')] };
+        expect(resolveArtifactCollections(explicitUndefined)).toBe(explicitUndefined);
+        const nullPackages = { packages: null, objects: [obj('o')] };
+        expect(resolveArtifactCollections(nullPackages)).toBe(nullPackages);
+    });
+
+    // A `packages` that is present but is not an array is MALFORMED, not absent
+    // (the rule beside `AssembledPackageBodySchema`). This reader used to hand
+    // such an artifact back by identity, answering about its top level while
+    // the loader refused the same bytes.
+    it.each([
+        ['{}', {}],
+        ['0', 0],
+        ["'x'", 'x'],
+    ])('refuses `packages: %s` with the resolver\'s INVALID_ARTIFACT_PACKAGES envelope', (_label, packages) => {
+        let raised: any;
+        try {
+            resolveArtifactCollections({ manifest: { id: 'com.example.a', name: 'A' }, objects: [obj('o')], packages });
+        } catch (err) {
+            raised = err;
+        }
+        expect(raised?.code).toBe('INVALID_ARTIFACT_PACKAGES');
+        expect(raised?.status).toBe(422);
+    });
+
+    it('lit controls for the refusal above: a well-formed `packages[]` resolves, and an absent key takes the single-package branch', () => {
+        // Without these two, an instrument that always threw would pin the
+        // three rows above just as green.
+        const wellFormed = resolveArtifactCollections({
+            packages: packagesOf({ objects: [obj('account')] }, { objects: [obj('order')] }),
+        }) as Record<string, any>;
+        expect(wellFormed.objects.map((o: any) => o.name)).toEqual(['account', 'order']);
+
+        const absent = { manifest: { id: 'com.example.a', name: 'A' }, objects: [obj('o')] };
+        expect(resolveArtifactCollections(absent)).toBe(absent);
     });
 
     it('returns the ARGUMENT ITSELF for an EMPTY `packages: []` too', () => {