fix(lint,spec): packagesOf refuses packages: null too, and lists its stamp under @objectstack/lint's ledger key

Rework round 1. Ruling A on #19926 (5805260775): `null` is malformed,
everywhere. `packages/lint`'s site census (#20206, ruling A on #15293) put
`null` out of scope with a pointer to #19926, but #19926's own claim fenced
`packages/lint` out as this card's surface -- the lint leg had no owner.

`packagesOf` (object-graph.ts) now treats only `undefined` as absent;
`null` falls to the same INVALID_ARTIFACT_PACKAGES refusal as `{}`/`0`/`'x'`/
a keyed object. The message names `null` as itself rather than `typeof`'s
`'object'`, matching the type label PR #20228 uses in
packages/core/src/artifact-packages.ts. Every `null` pin flips from a
silence control to a refusal assertion, at `packagesOf` directly and at
each of the three public functions its four (now five, with
validate-mapping-target-fields.ts) call sites sit behind. `undefined`
(absent) and a well-formed array stay green controls.

CI fix: `check:error-code-provenance` (job "Lint & Repo Gates", step 120)
was red on the prior head -- `packages/lint` stamps the registered code
`INVALID_ARTIFACT_PACKAGES` (object-graph.ts's `err.code = ...`) without
being listed under its own owner key in `ERROR_CODE_LEDGER`. Fixed the way
the gate prescribes: a new `'@objectstack/lint'` row in
packages/spec/src/api/error-code-ledger.zod.ts, with a comment recording
the wire path (door: 'none' -- packages/lint's rules are pure
`(stack) => Finding[]` functions called from `os validate`/`os lint`/
`os build`, never through an HTTP boundary). No code minted or duplicated;
the existing registered code is reused, provenance is merely now recorded
under a second owner (precedent: 3f9e2ea, "list plugin-security's
class-field error codes under its own ledger key").

Two changesets: `@objectstack/lint: minor` (Clause-②: no (narrowing) --
unchanged from round 1) for the behavior change, and a new
`@objectstack/spec: minor` (Clause-②: yes) for the ledger row -- a new
per-package face on a published payload, modelled on the 3f9e2ea
precedent's own spec-only changeset. The PR-level declaration becomes
`Clause-②: yes (narrowing)`, carrying both facts.

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

Author: claude

.changeset/20206-lint-error-code-provenance-row.md

@@ -0,0 +1,9 @@
+---
+"@objectstack/spec": minor
+---
+
+`ERROR_CODE_LEDGER['@objectstack/lint']` now lists `INVALID_ARTIFACT_PACKAGES`, the code `packages/lint`'s `packagesOf` reader stamps for a malformed `stack.packages` (#20206) — required by `check:error-code-provenance`, which refuses a registered code stamped by a package whose own owner key does not list it.
+
+Clause-②: yes
+
+Provenance, not identity: the code was already registered under `@objectstack/core` (`resolveArtifactPackageOrder`, the producer `packagesOf` deliberately mirrors rather than mints a new code for), so the `ErrorCode` union, the wire, and every other package's rows are unchanged. What widens is the per-package face a consumer reads from `ERROR_CODE_LEDGER['@objectstack/lint']`, newly present where it was absent before. Nothing to migrate.

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

@@ -2,12 +2,12 @@
 "@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).
+`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).
 
 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.
+- **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 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

@@ -307,15 +307,11 @@ describe('object-graph — packagesOf (#20206, ruling A on #15293 `5634034754`)'
     expect(packagesOf({ packages: [null, valid, undefined, 'junk', 42, []] })).toEqual([valid]);
   });
 
-  it('an absent `packages` stays silent — `[]`, not a refusal', () => {
+  it('CONTROL — only an absent (`undefined`) `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: {} } }],
@@ -331,6 +327,19 @@ describe('object-graph — packagesOf (#20206, ruling A on #15293 `5634034754`)'
       new RegExp(`\`packages\` of type ${typeof shape}`),
     );
   });
+
+  // [ruling A on #19926, `5805260775`] `null` is malformed, everywhere — it is
+  // PRESENT, not absent, so it takes the same refusal as `{}`/`0`/`'x'`, not
+  // the silent branch above. `typeof null` is `'object'`, which would name a
+  // `{}` the author never wrote, so the message names `null` as itself
+  // (matching `resolveArtifactPackageOrder` in `@objectstack/core`, PR #20228).
+  it('refuses `packages: null` too — malformed, not absent (ruling `5805260775` on #19926)', () => {
+    expect(() => packagesOf({ packages: null })).toThrow(
+      expect.objectContaining({ code: 'INVALID_ARTIFACT_PACKAGES', status: 422 }),
+    );
+    expect(() => packagesOf({ packages: null })).toThrow(/`packages` of type null/);
+    expect(() => packagesOf({ packages: null })).not.toThrow(/of type object/);
+  });
 });
 
 /**

packages/lint/src/object-graph.ts

@@ -239,16 +239,17 @@ export type StackPackagesError = Error & { code: string; status: number };
  * 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
+ * - **Absent** (`undefined` ONLY) → `[]`. 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.)
+ *   never "what does this stack provide". `null` is malformed, per ruling
+ *   `5805260775` on #19926.
  * - **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).
+ * - **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).
  *
  * ⛔ Do not fold this into `recordsOf` itself (#20206's card): that reader
  * stays the shared map-or-array reader its other callers need.
@@ -260,13 +261,19 @@ export type StackPackagesError = Error & { code: string; status: number };
  */
 export function packagesOf(stack: unknown): AnyRec[] {
   const declared = (stack as { packages?: unknown } | null | undefined)?.packages;
-  if (declared === undefined || declared === null) return [];
+  // ⛔ `undefined` ONLY. `null` is present, not absent — ruling `5805260775`
+  // on #19926 — so it falls to the refusal below with every other non-array
+  // value.
+  if (declared === undefined) 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.',
+    // `typeof null` is `'object'`, which would name a `{}` the author never
+    // wrote; `null` is named as itself (matching `resolveArtifactPackageOrder`
+    // in `@objectstack/core`).
+    + `${declared === null ? 'null' : 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;

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

@@ -107,9 +107,11 @@ describe('validateMappingTargetFields', () => {
   // 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.
+  // malformed, not absent; only `undefined` stays silent. `null` joins this
+  // set in rework round 1 (ruling A on #19926, `5805260775`): it is present,
+  // not absent.
   it('refuses a PRESENT non-array `packages` instead of silently ignoring it', () => {
-    for (const packages of [{}, 0, 'x']) {
+    for (const packages of [{}, 0, 'x', null]) {
       expect(() => validateMappingTargetFields({
         objects: [contact],
         packages,

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

@@ -297,18 +297,20 @@ describe('validateObjectReferences — artifact packages[] as resolution context
     expect(findings[0].path).toBe('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));
+  it('CONTROL — `packages: undefined` (absent) stays silent — the only value this reader treats as absent', () => {
+    const findings = validateObjectReferences(perPackageStack(ORDERS_BODY, undefined));
     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.
+  // that is not a list of entries" — `null`, `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. `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.
   it('refuses a PRESENT non-array `packages` instead of silently ignoring it', () => {
-    for (const packages of [42, 'core']) {
+    for (const packages of [null, 42, 'core']) {
       expect(() => validateObjectReferences(perPackageStack(ORDERS_BODY, packages))).toThrow(
         expect.objectContaining({ code: 'INVALID_ARTIFACT_PACKAGES', status: 422 }),
       );

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

@@ -543,16 +543,18 @@ describe('validateTranslationReferences — a PRESENT non-array `packages` (#202
   const oneBundle = [{ 'zh-CN': { objects: {} } }];
 
   it('refuses instead of silently treating it as absent', () => {
-    for (const packages of [{}, 0, 'x', { a: { manifest: {} } }]) {
+    for (const packages of [{}, 0, 'x', { a: { manifest: {} } }, null]) {
       expect(() => validateTranslationReferences({ objects: [], translations: oneBundle, packages })).toThrow(
         expect.objectContaining({ code: 'INVALID_ARTIFACT_PACKAGES', status: 422 }),
       );
     }
   });
 
-  it('CONTROL — an absent or `null` `packages` stays silent', () => {
+  // [ruling A on #19926, `5805260775`] `null` moved from the control above
+  // into the refusal set in rework round 1: it is present, not absent.
+  it('CONTROL — only an absent (`undefined`) `packages` stays silent', () => {
     expect(validateTranslationReferences({ objects: [], translations: oneBundle })).toEqual([]);
-    expect(validateTranslationReferences({ objects: [], translations: oneBundle, packages: null })).toEqual([]);
+    expect(validateTranslationReferences({ objects: [], translations: oneBundle, packages: undefined })).toEqual([]);
   });
 });
 

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

@@ -1356,6 +1356,20 @@ export const ERROR_CODE_LEDGER = {
     'STACK_COMPOSE_KEY_CONFLICT',                // a single-valued top-level key is declared with different values by two stacks
     'STACK_COMPOSE_OBJECT_CONFLICT',             // the same object name is defined by more than one stack under the default `objectConflict: 'error'`
   ],
+  '@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.
+    'INVALID_ARTIFACT_PACKAGES',
+  ],
 } as const satisfies Record<string, readonly string[]>;
 
 /** A code registered by at least one package (deduped union of the ledger). */