fix(lint): refuse a present non-array stack.packages at all five recordsOf(stack.packages) readers

Ruling A on #15293 (comment 5634034754): a `packages` that is present but not
an array (`{}`, `0`, `'x'`, a keyed object) is malformed, not absent, and
every reader refuses it. Four `packages/lint` readers fell through
`recordsOf(stack.packages)` to `[]` instead of refusing:
`validate-object-references.ts`'s `artifactProvidedObjectNames`, and
`validate-translation-references.ts`'s `contributedNavItemsByApp`,
`objectExtensionsByTarget` and `artifactProvidedRecords`. A fifth copy of the
same pattern (`validate-mapping-target-fields.ts`'s `extensionFieldsByTarget`)
landed via #20208 after this ruling's site census and is fixed the same way.

All five now share one small reader, `packagesOf(stack)`
(`object-graph.ts`): absent stays `[]`, an array is read exactly as
`recordsOf` read it (junk entries dropped, unchanged), and anything else
present throws `INVALID_ARTIFACT_PACKAGES` (ADR-0112, status 422) -- the same
registered code `@objectstack/core`'s `resolveArtifactPackageOrder` already
raises for the identical defect. `recordsOf` itself is untouched: it stays
the shared map-or-array reader `objects`/`sections`/`tabs` need, where a
keyed map is legitimate -- `packages` never has a map form, so this is a
second, narrower reader rather than a branch on the first one.

Pins: `packagesOf` is pinned exhaustively (array control, absent/null
silence, refusal on `{}`/`0`/`'x'`/a keyed object, with code + status). Each
of the three public functions these readers sit behind
(`validateObjectReferences`, `validateTranslationReferences`,
`validateMappingTargetFields`) gets one throw-pin proving the wiring reaches
the shared reader. One existing pin asserted the old fall-through semantics
(`validate-object-references.test.ts`, "ignores a `packages` value that is
not a list of entries") and is flipped: `null` stays a silence control,
`42`/`'core'` now assert the refusal.

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

Author: claude

.changeset/20206-lint-packages-non-array-refused.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/lint": minor
+---
+
+`packages/lint`'s four `stack.packages` readers (plus a fifth added by #20208 after this ruling's own site census) now refuse a PRESENT non-array `packages` — `{}`, `0`, `'x'`, or a keyed object — the same way `@objectstack/core`'s `resolveArtifactPackageOrder` already does, instead of silently reading it as "no packages" (#20206, ruling A on #15293, comment 5634034754).
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) an already-malformed `packages` value is refused rather than converted; no key, export or stored value moves, and nothing in this repo emits the shape today -->
+
+- **What changes**: `validateObjectReferences`, `validateTranslationReferences` and `validateMappingTargetFields` (the three public `@objectstack/lint` functions these readers sit behind) now throw an `INVALID_ARTIFACT_PACKAGES` error (ADR-0112, `status: 422`) instead of returning findings, when the stack they are handed carries a `packages` key that is present but not an array. `os validate` / `os lint` / `os build` surface it as a refusal on stderr (and in `error`/`code` under `--json`) instead of reporting the stack as clean.
+- **What does not change**: an absent `packages`, and `packages: null`, are still read as "no packages" — unchanged, and #19926's surface, not this one. A well-formed `packages[]` array is read exactly as before, junk entries dropped exactly as before.
+- **Fix**: write `packages` as an array of `{ manifest: … }` entries, or omit the key entirely for a single-package stack.

packages/lint/src/object-graph.test.ts

@@ -14,6 +14,7 @@ import {
   isUnjudgeable,
   nearestName,
   listNames,
+  packagesOf,
   RELATIONSHIP_FIELD_TYPES,
 } from './object-graph.js';
 import { walkFilterFieldKeys, type FilterFieldKey } from './filter-walk.js';
@@ -292,6 +293,46 @@ describe('object-graph — a non-record entry in `stack.objects` (#15494)', () =
   });
 });
 
+describe('object-graph — packagesOf (#20206, ruling A on #15293 `5634034754`)', () => {
+  // `packages` is declared `z.array(ArtifactPackageSchema).optional()` — array
+  // or absent, never map-or-array like `objects`/`sections`/`tabs`. A PRESENT
+  // non-array `packages` ({}, 0, 'x', a keyed object) is malformed, not
+  // absent, and every reader refuses it. This is the ONE reader the four
+  // `packages/lint` call sites now share, replacing four private copies of
+  // `recordsOf(stack.packages)`.
+
+  it('CONTROL — an array is read exactly as `recordsOf` read it: iterated, junk dropped', () => {
+    const valid = { manifest: { id: 'com.example.a' } };
+    expect(packagesOf({ packages: [valid] })).toEqual([valid]);
+    expect(packagesOf({ packages: [null, valid, undefined, 'junk', 42, []] })).toEqual([valid]);
+  });
+
+  it('an absent `packages` stays silent — `[]`, not a refusal', () => {
+    expect(packagesOf({})).toEqual([]);
+    expect(packagesOf({ packages: undefined })).toEqual([]);
+  });
+
+  it('`packages: null` also stays silent here — #19926 owns that disagreement, not this reader', () => {
+    expect(packagesOf({ packages: null })).toEqual([]);
+  });
+
+  it.each([
+    ['an empty object', {}],
+    ['a keyed object (the shape `recordsOf` would have read as a map)', { a: { manifest: {} } }],
+    ['a number', 0],
+    ['a string', 'x'],
+  ])('refuses a PRESENT non-array `packages` — %s', (_label, shape) => {
+    expect(() => packagesOf({ packages: shape })).toThrow(
+      expect.objectContaining({ code: 'INVALID_ARTIFACT_PACKAGES', status: 422 }),
+    );
+    // The message names the actual runtime type, so an author sees what they
+    // wrote rather than a generic "malformed" sentence.
+    expect(() => packagesOf({ packages: shape })).toThrow(
+      new RegExp(`\`packages\` of type ${typeof shape}`),
+    );
+  });
+});
+
 /**
  * [#19289] A `{ type: 'user' }` field with no `reference` is TRAVERSABLE — the
  * third defect found by the implicit-target census, and the widest-reaching of

packages/lint/src/object-graph.ts

@@ -220,6 +220,59 @@ export function recordsOf(v: unknown): AnyRec[] {
   return [];
 }
 
+/** The shape a thrown {@link packagesOf} refusal carries (ADR-0112 envelope). */
+export type StackPackagesError = Error & { code: string; status: number };
+
+/**
+ * Every entry of `stack.packages` — the release artifact's package list
+ * (ADR-0130 D4) — read the way {@link resolveArtifactPackageOrder}
+ * (`@objectstack/core`) reads it, ⛔ NOT the way {@link recordsOf} reads
+ * `objects` / `sections` / `tabs`.
+ *
+ * `packages` is declared `z.array(ArtifactPackageSchema).optional()`
+ * (`ObjectStackDefinitionSchema`, `@objectstack/spec`) — array-or-absent,
+ * never map-or-array. Ruling A on #15293 (`5634034754`): a `packages` that is
+ * PRESENT but not an array (`{}`, `0`, `'x'`, or a keyed object) is
+ * **malformed, not absent**, and every reader refuses it — `recordsOf` cannot
+ * be that reader, because for its OTHER callers a plain object legitimately
+ * IS the map form (see the note above this function). `packages` has no map
+ * form at all, so this is a second, narrower reader rather than a branch on
+ * the first one.
+ *
+ * - **Absent** (`undefined` / `null`) → `[]`. A single-package artifact
+ *   contributes nothing here — this answers "what does `packages[]` add",
+ *   never "what does this stack provide". (`null` is left exactly this way
+ *   on purpose — #19926 owns that disagreement, not this function.)
+ * - **An array** → iterated, non-record members dropped — unchanged from
+ *   what every one of these four call sites did through `recordsOf` before
+ *   this function existed.
+ * - **Anything else present** → refused, once, here — replacing four copies
+ *   of the same read across `validate-object-references.ts` and
+ *   `validate-translation-references.ts` (#20206).
+ *
+ * ⛔ Do not fold this into `recordsOf` itself (#20206's card): that reader
+ * stays the shared map-or-array reader its other callers need.
+ *
+ * @throws A {@link StackPackagesError} — `code: 'INVALID_ARTIFACT_PACKAGES'`,
+ *   `status: 422`, the SAME registered code `resolveArtifactPackageOrder`
+ *   raises for the identical defect on the assembled artifact — never a new
+ *   one.
+ */
+export function packagesOf(stack: unknown): AnyRec[] {
+  const declared = (stack as { packages?: unknown } | null | undefined)?.packages;
+  if (declared === undefined || declared === null) return [];
+  if (Array.isArray(declared)) return declared.filter(isRec);
+  const err = new Error(
+    'A stack\'s `packages` must be an array of package entries (ADR-0130 D4, '
+    + '`ArtifactPackageSchema`), but this stack carries `packages` of type '
+    + `${typeof declared}. Omit the key entirely for a single-package stack — `
+    + '`manifest` is retained, not replaced.',
+  ) as StackPackagesError;
+  err.code = 'INVALID_ARTIFACT_PACKAGES';
+  err.status = 422;
+  throw err;
+}
+
 function strName(v: unknown): string | undefined {
   return typeof v === 'string' && v.length > 0 ? v : undefined;
 }

packages/lint/src/validate-mapping-target-fields.test.ts

@@ -103,6 +103,21 @@ describe('validateMappingTargetFields', () => {
     expect(validateMappingTargetFields(stack)).toEqual([]);
   });
 
+  // [#20206, ruling A on #15293 `5634034754`] This reader was added by #20208
+  // after the ruling's own site census (`origin/main` `1c8b320`) — a fifth
+  // copy of the same `recordsOf(stack.packages)` fall-through the ruling
+  // closes elsewhere in this package. A PRESENT non-array `packages` is
+  // malformed, not absent; only `undefined`/`null` stay silent.
+  it('refuses a PRESENT non-array `packages` instead of silently ignoring it', () => {
+    for (const packages of [{}, 0, 'x']) {
+      expect(() => validateMappingTargetFields({
+        objects: [contact],
+        packages,
+        mappings: [mapping([{ source: 'Tier', target: 'sla_tier' }])],
+      })).toThrow(expect.objectContaining({ code: 'INVALID_ARTIFACT_PACKAGES', status: 422 }));
+    }
+  });
+
   it('stays silent on a mapping whose object this stack does not define (skip 1)', () => {
     expect(validateMappingTargetFields({
       objects: [contact],

packages/lint/src/validate-mapping-target-fields.ts

@@ -48,7 +48,7 @@
 
 import { indexImportMappingTargets, unknownImportMappingTargets } from '@objectstack/spec/data';
 
-import { listNames, recordsOf, suggestName } from './object-graph.js';
+import { listNames, packagesOf, recordsOf, suggestName } from './object-graph.js';
 
 /** A `fieldMapping[].target` that names no field of the mapping's object. */
 export const MAPPING_TARGET_FIELD_UNKNOWN = 'mapping-target-field-unknown';
@@ -92,7 +92,7 @@ function extensionFieldsByTarget(stack: AnyRec): Map<string, AnyRec[]> {
     }
   };
   add(stack.objectExtensions);
-  for (const entry of recordsOf(stack.packages)) {
+  for (const entry of packagesOf(stack)) {
     if (isRec(entry.manifest)) add(entry.manifest.objectExtensions);
   }
   return byTarget;

packages/lint/src/validate-object-references.test.ts

@@ -297,10 +297,21 @@ describe('validateObjectReferences — artifact packages[] as resolution context
     expect(findings[0].path).toBe('objects[0].fields.account.reference');
   });
 
-  it('ignores a `packages` value that is not a list of entries', () => {
-    for (const packages of [null, 42, 'core']) {
-      const findings = validateObjectReferences(perPackageStack(ORDERS_BODY, packages));
-      expect(findings.map((f) => f.path)).toEqual(['objects[0].fields.account.reference']);
+  it('`packages: null` stays absent, unlike a present non-array value (#19926 owns `null`, not this rule)', () => {
+    const findings = validateObjectReferences(perPackageStack(ORDERS_BODY, null));
+    expect(findings.map((f) => f.path)).toEqual(['objects[0].fields.account.reference']);
+  });
+
+  // [#20206, ruling A on #15293 `5634034754`] Was "ignores a `packages` value
+  // that is not a list of entries" — `42` and `'core'` used to fall through
+  // `recordsOf` to `[]` and be silently treated as "no packages", exactly the
+  // fall-through the ruling closes: PRESENT but not an array is malformed, not
+  // absent, and every reader refuses it.
+  it('refuses a PRESENT non-array `packages` instead of silently ignoring it', () => {
+    for (const packages of [42, 'core']) {
+      expect(() => validateObjectReferences(perPackageStack(ORDERS_BODY, packages))).toThrow(
+        expect.objectContaining({ code: 'INVALID_ARTIFACT_PACKAGES', status: 422 }),
+      );
     }
   });
 });

packages/lint/src/validate-object-references.ts

@@ -81,7 +81,7 @@ import {
 } from '@objectstack/spec/system';
 import { referenceCarrierOf, referenceTargetOf } from '@objectstack/spec/data';
 
-import { recordsOf, suggestName } from './object-graph.js';
+import { packagesOf, recordsOf, suggestName } from './object-graph.js';
 
 /** Materialized once for the repeated edit-distance scans in `suggestName`. */
 const PLATFORM_NAMES: readonly string[] = [...PLATFORM_PROVIDED_OBJECT_NAMES];
@@ -162,7 +162,7 @@ function isInterpolated(target: string): boolean {
  */
 function artifactProvidedObjectNames(stack: AnyRec): string[] {
   const names: string[] = [];
-  for (const entry of recordsOf(stack.packages)) {
+  for (const entry of packagesOf(stack)) {
     const body = entry.manifest;
     if (!body || typeof body !== 'object' || Array.isArray(body)) continue;
     for (const obj of recordsOf((body as AnyRec).objects)) {

packages/lint/src/validate-translation-references.test.ts

@@ -528,6 +528,34 @@ describe('validateTranslationReferences — cross-package objects (§4 ladder)',
   });
 });
 
+describe('validateTranslationReferences — a PRESENT non-array `packages` (#20206, ruling A on #15293 `5634034754`)', () => {
+  // `packages` is declared array-or-absent (ADR-0130 D4), never map-or-array.
+  // This rule reads it through the three internal carriers `object-graph.ts`'s
+  // `packagesOf` now serves (contributed nav, object extensions, and every
+  // artifact-provided collection) — all three now refuse instead of silently
+  // reading the malformed value as "no packages". `artifactProvidedRecords`
+  // ('objects') runs first inside `buildUniverse`, so that is the carrier this
+  // pin observes throwing; the read itself is pinned exhaustively, once, in
+  // `object-graph.test.ts` (the shared function all three now call).
+  // A bundle is required — `validateTranslationReferences` returns before ever
+  // calling `buildUniverse` (and therefore before reading `packages` at all)
+  // when `stack.translations` is empty, exactly like the exemptions below.
+  const oneBundle = [{ 'zh-CN': { objects: {} } }];
+
+  it('refuses instead of silently treating it as absent', () => {
+    for (const packages of [{}, 0, 'x', { a: { manifest: {} } }]) {
+      expect(() => validateTranslationReferences({ objects: [], translations: oneBundle, packages })).toThrow(
+        expect.objectContaining({ code: 'INVALID_ARTIFACT_PACKAGES', status: 422 }),
+      );
+    }
+  });
+
+  it('CONTROL — an absent or `null` `packages` stays silent', () => {
+    expect(validateTranslationReferences({ objects: [], translations: oneBundle })).toEqual([]);
+    expect(validateTranslationReferences({ objects: [], translations: oneBundle, packages: null })).toEqual([]);
+  });
+});
+
 describe('validateTranslationReferences — apps, dashboards, global actions', () => {
   const stack = {
     objects: [{ name: 'crm_lead', fields: { name: { type: 'text' } } }],

packages/lint/src/validate-translation-references.ts

@@ -167,7 +167,7 @@
 import { expandViewContainer } from '@objectstack/spec';
 import { hasPlatformObjectPrefix, isPlatformProvidedObjectName } from '@objectstack/spec/system';
 import { walkFlowNodes } from './flow-walk.js';
-import { recordsOf, suggestName } from './object-graph.js';
+import { packagesOf, recordsOf, suggestName } from './object-graph.js';
 import { walkPageComponents } from './page-walk.js';
 import { SYSTEM_FIELDS } from './system-fields.js';
 import { viewObjectName } from './view-walk.js';
@@ -750,7 +750,7 @@ function contributedNavItemsByApp(stack: AnyRec): Map<string, unknown[]> {
     }
   };
   add(isRec(stack.manifest) ? stack.manifest.navigationContributions : undefined);
-  for (const entry of recordsOf(stack.packages)) {
+  for (const entry of packagesOf(stack)) {
     const body = entry.manifest;
     if (!isRec(body)) continue;
     add(body.navigationContributions);
@@ -845,7 +845,7 @@ function objectExtensionsByTarget(stack: AnyRec): Map<string, AnyRec[]> {
     }
   };
   add(stack.objectExtensions);
-  for (const entry of recordsOf(stack.packages)) {
+  for (const entry of packagesOf(stack)) {
     const body = entry.manifest;
     if (!isRec(body)) continue;
     add(body.objectExtensions);
@@ -918,7 +918,7 @@ function objectExtensionsByTarget(stack: AnyRec): Map<string, AnyRec[]> {
  */
 function artifactProvidedRecords(stack: AnyRec, collection: string): AnyRec[] {
   const provided: AnyRec[] = [];
-  for (const entry of recordsOf(stack.packages)) {
+  for (const entry of packagesOf(stack)) {
     const body = entry.manifest;
     if (!isRec(body)) continue;
     provided.push(...recordsOf(body[collection]));