fix(lint,spec): close the round-2 pin gap and correct false-at-head wording

REWORK round 2 for #20206 (at-tier record 5856823202, items 1-2):

1. `validate-object-references.test.ts`'s non-array refusal test pinned
   only [null, 42, 'core']; add `{}` and a keyed object so all three
   validators pin the identical set `packagesOf` itself does.
2. Text corrected to match the head, wording only:
   (a) "four call sites" / "four copies" -> "five ... three files" in
       the `packagesOf` docblock and the `object-graph.test.ts` comment,
       now that `validate-mapping-target-fields.ts` is a fifth site.
   (b) every sentence claiming lint reads `null` "the way
       `resolveArtifactPackageOrder` does" or raises "the SAME code ...
       for the identical defect" is qualified for `null` specifically:
       on `main`, core still reads `null` as absent and names it via
       `typeof`; that only changes once #19926 (PR #20228) lands. Fixed
       in the docblock, the inline naming comment, the lint changeset
       and the ledger-row comment in `error-code-ledger.zod.ts`.
   (c) the lint changeset's door-reachability claim corrected: only
       `os lint` reaches `packagesOf`'s refusal (exit 1, message on
       stdout via `printError`, `code` under `--json`); `os validate`
       and `os build` already refuse a malformed `packages` earlier, at
       `ObjectStackDefinitionSchema.safeParse`, before these rules run
       (re-read `validate.ts:293`, `compile.ts:356`, `lint.ts:673/1140`,
       `format.ts:369` directly to confirm).

No `packagesOf` semantics changed.

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

@@ -2,12 +2,12 @@
 "@objectstack/lint": minor
 ---
 
-`packages/lint`'s five `stack.packages` readers (four named by #20206, plus one added by #20208 after that card's site census) now refuse a PRESENT non-array `packages` — `{}`, `0`, `'x'`, a keyed object, and (as of this round) `null` too — the same way `@objectstack/core`'s `resolveArtifactPackageOrder` already does, instead of silently reading it as "no packages" (#20206, ruling A on #15293 comment 5634034754; the `null` leg is ruling A on #19926, comment 5805260775: `null` is malformed, everywhere).
+`packages/lint`'s five `stack.packages` readers (four named by #20206, plus one added by #20208 after that card's site census) now refuse a PRESENT non-array `packages` — `{}`, `0`, `'x'`, a keyed object, and (as of this round) `null` too — instead of silently reading it as "no packages" (#20206, ruling A on #15293 comment 5634034754; the `null` leg is ruling A on #19926, comment 5805260775: `null` is malformed, everywhere). For every shape other than `null`, this is the same way `@objectstack/core`'s `resolveArtifactPackageOrder` already refuses it, with the same registered code; for `null`, `resolveArtifactPackageOrder` still reads it as absent on `main`, and the two readers align only once #19926 (PR #20228) lands.
 
 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 — `null` included. `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 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 — `null` included. Only `os lint` reaches this refusal — exit 1, the message on stdout (`printError`), `code` under `--json`; `os validate` and `os build` already refuse a malformed `packages` earlier, at `ObjectStackDefinitionSchema.safeParse`, before these rules ever run.
 - **What does not change**: an absent `packages` (the key omitted, or explicitly `undefined`) is still read as "no packages" — unchanged. 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

@@ -297,8 +297,8 @@ 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
+  // absent, and every reader refuses it. This is the ONE reader the five
+  // `packages/lint` call sites now share, replacing five private copies of
   // `recordsOf(stack.packages)`.
 
   it('CONTROL — an array is read exactly as `recordsOf` read it: iterated, junk dropped', () => {

packages/lint/src/object-graph.ts

@@ -225,9 +225,8 @@ 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`.
+ * (ADR-0130 D4) — read on `packages/lint`'s own terms, ⛔ NOT the way
+ * {@link recordsOf} reads `objects` / `sections` / `tabs`.
  *
  * `packages` is declared `z.array(ArtifactPackageSchema).optional()`
  * (`ObjectStackDefinitionSchema`, `@objectstack/spec`) — array-or-absent,
@@ -242,22 +241,27 @@ export type StackPackagesError = Error & { code: string; status: number };
  * - **Absent** (`undefined` ONLY) → `[]`. A single-package artifact
  *   contributes nothing here — this answers "what does `packages[]` add",
  *   never "what does this stack provide". `null` is malformed, per ruling
- *   `5805260775` on #19926.
+ *   `5805260775` on #19926 — for `null` specifically, that disagrees with
+ *   {@link resolveArtifactPackageOrder} (`@objectstack/core`), which on
+ *   `main` still reads `null` as absent; the two readers align once #19926
+ *   (PR #20228) lands.
  * - **An array** → iterated, non-record members dropped — unchanged from
- *   what every one of these four call sites did through `recordsOf` before
+ *   what every one of these five call sites did through `recordsOf` before
  *   this function existed.
  * - **Anything else present, `null` included** → refused, once, here —
- *   replacing four copies of the same read across
- *   `validate-object-references.ts` and `validate-translation-references.ts`
- *   (#20206).
+ *   replacing five copies of the same read across
+ *   `validate-object-references.ts`, `validate-translation-references.ts`
+ *   and `validate-mapping-target-fields.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.
+ *   `status: 422` — for a present non-array `packages` OTHER than `null`,
+ *   the SAME registered code {@link resolveArtifactPackageOrder} already
+ *   raises for the identical defect on the assembled artifact; for `null`,
+ *   only once #19926 (PR #20228) lands does core raise it too. Never a new
+ *   code, either way.
  */
 export function packagesOf(stack: unknown): AnyRec[] {
   const declared = (stack as { packages?: unknown } | null | undefined)?.packages;
@@ -270,8 +274,9 @@ export function packagesOf(stack: unknown): AnyRec[] {
     'A stack\'s `packages` must be an array of package entries (ADR-0130 D4, '
     + '`ArtifactPackageSchema`), but this stack carries `packages` of type '
     // `typeof null` is `'object'`, which would name a `{}` the author never
-    // wrote; `null` is named as itself (matching `resolveArtifactPackageOrder`
-    // in `@objectstack/core`).
+    // wrote; `null` is named as itself here — the naming #19926 (PR #20228)
+    // gives `resolveArtifactPackageOrder` once it lands, adopted early by
+    // this reader.
     + `${declared === null ? 'null' : typeof declared}. Omit the key entirely for a `
     + 'single-package stack — `manifest` is retained, not replaced.',
   ) as StackPackagesError;

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

@@ -308,9 +308,11 @@ describe('validateObjectReferences — artifact packages[] as resolution context
   // exactly the fall-through the ruling closes: PRESENT but not an array is
   // malformed, not absent, and every reader refuses it. `null` joins this set
   // in rework round 1 (ruling A on #19926, `5805260775`): it is present, not
-  // absent, so it is no longer a control.
+  // absent, so it is no longer a control. `{}` and a keyed object join in
+  // rework round 2, so this validator pins the same set `packagesOf` and the
+  // other two validators do.
   it('refuses a PRESENT non-array `packages` instead of silently ignoring it', () => {
-    for (const packages of [null, 42, 'core']) {
+    for (const packages of [null, 42, 'core', {}, { a: { manifest: {} } }]) {
       expect(() => validateObjectReferences(perPackageStack(ORDERS_BODY, packages))).toThrow(
         expect.objectContaining({ code: 'INVALID_ARTIFACT_PACKAGES', status: 422 }),
       );

packages/spec/src/api/error-code-ledger.zod.ts

@@ -1359,16 +1359,21 @@ export const ERROR_CODE_LEDGER = {
   ],
   '@objectstack/lint': [
     // [#20206] `packagesOf` (`object-graph.ts`) refuses a present non-array
-    // `stack.packages` ({}, 0, 'x', a keyed object, `null`) with the SAME
-    // registered code `@objectstack/core`'s `resolveArtifactPackageOrder`
-    // raises for the identical defect on an assembled artifact (ruling A on
-    // #15293 `5634034754`; the `null` leg is ruling A on #19926 `5805260775`)
-    // — deliberately reused, never minted, so an author sees one code
-    // regardless of which reader catches the malformed shape first. `door:
-    // 'none'`, the #16449 reading: `packages/lint`'s rules are pure
-    // `(stack) => Finding[]` functions called from `os validate` / `os lint`
-    // / `os build` (`packages/cli`), never through an HTTP boundary — the
-    // same posture `@objectstack/spec`'s own `STACK_*` rows above record.
+    // `stack.packages` ({}, 0, 'x', a keyed object, `null`) — for every shape
+    // OTHER than `null`, with the SAME registered code `@objectstack/core`'s
+    // `resolveArtifactPackageOrder` already raises for the identical defect
+    // on an assembled artifact (ruling A on #15293 `5634034754`). For `null`
+    // (ruling A on #19926 `5805260775`), core still reads it as absent on
+    // `main`; core raises this code for `null` too only once #19926 (PR
+    // #20228) lands — deliberately reused either way, never minted, so an
+    // author sees one code regardless of which reader catches the malformed
+    // shape first. `door: 'none'`, the #16449 reading: `packages/lint`'s
+    // rules are pure `(stack) => Finding[]` functions, reachable only from
+    // `os lint` (`packages/cli`) — `os validate` / `os build` refuse a
+    // malformed `packages` earlier, at `ObjectStackDefinitionSchema.safeParse`,
+    // before these rules ever run — never through an HTTP boundary either
+    // way, the same posture `@objectstack/spec`'s own `STACK_*` rows above
+    // record.
     'INVALID_ARTIFACT_PACKAGES',
   ],
 } as const satisfies Record<string, readonly string[]>;