fix: four defects a widened review found in unreviewed work

A code review of the @sortableDefaultOrder thread found six defects, two of them
gates left red. That hit rate argued for widening to the commits nobody had
looked at, scoped by blast radius rather than by date: the three marked breaking
plus two codegen-correctness ones. It found a REGRESSION, not just latent debt.

1. outputLayout "package" — the fix was HALF-APPLIED and shipped a regression.
   The built-in barrel moved to effectivePackage(); the four reference/owned
   copies — the ones `meta init` actually scaffolds — kept the bare `.package`
   read and merely gained an unused import. Their emitted index.ts exported
   "./Widget" for a file at acme/commerce/Widget.ts: TS2307 on a project with
   nothing wrong with it. It is a regression rather than a leftover, because
   before the change the entity files landed flat too and the barrel agreed with
   them.

   The gate could not see it. It asserts on EMITTED PATHS, and a barrel's path is
   correct whatever it exports — a wrong import SPECIFIER is structurally out of
   its reach, so the earlier claim that "a new generator reaching for .package
   again fails without anyone maintaining a list" was not true of the barrel. It
   now also runs the barrel and requires every export specifier to name a file
   the same run actually wrote; proven by reverting, which names "Widget".

   The comment that caused the defect was still in place stating the opposite of
   the code — it told the reader to pass obj.package "for consistency with the
   emitter", which is how the bare read propagated. Rewritten to say why
   consistency with a wrong emitter is not a reason. Three leftover unused
   effectivePackage imports removed; nothing flagged them, as the workspace sets
   no noUnusedLocals.

2. attr("isArray") guarded ONE door of four. attr()/hasAttr() threw; ownAttr(),
   ownHasAttr() and ownMetaAttr() asked the identical forbidden question and
   answered it just as silently, and ownAttr is a documented public accessor an
   owned generator can reach for. One rule with four doors, three still open, is
   this repo's most-repeated defect shape. All four now guarded, `value` still
   exempt (an attr node reads its own payload through ownAttr(RESERVED_KEY_VALUE),
   so the exemption must be settled before the guard). The derived test covers
   all four, and its header now says what the derivation does NOT reach:
   STRUCTURAL_KEYWORD_ACCESSORS is hand-written, so a keyword added to
   RESERVED_KEYS and not to that map gets no runtime guard — the loop goes red
   and says so, which is the forcing function.

   Five parser tests used ownHasAttr as the negative probe for "this reserved key
   is not stored as an attr". They now read ownAttrs(), which is literally the
   attr map each assertion's own description names.

3. The useEntityFetcher -> useEntityPathFetcher rename left four shipped surfaces
   on the old name, including the metaobjects-runtime-ui agent-context skill
   `meta init` installs into every project. It described the hook as "reads the
   fetcher from context (generated hooks call this)" — both halves false, and the
   omitted half is exactly the path rewrite the rename exists to warn about. That
   is the third time a shipped skill has taught something the code had already
   changed, so the two agent-context-conformance fixtures move with it.

4. Three tier-1 adopter docs still presented `bigserial(...)` in blocks headed as
   generated output; `meta gen` has emitted bigint(...) +
   .generatedByDefaultAsIdentity() since the identity fix. No gate covers these
   blocks — the doc-examples gate loads fenced METADATA only.

Also adds CHANGELOG entries for all five reviewed commits. Three were marked
breaking and none had one: a throw added to a core public API, a public export
rename, and a gate whose verdict logic changed.

Verified: workspace typecheck clean; ci-local --quick green (incl. owned-template
-copies and site-reference freshness); sdk 304, codegen-ts 1575, metadata 2616,
cli 838, tanstack 49, runtime-web 55 — all passing.

Not fixed here, reported for judgment: docs-drift's `checked` count is machine-
dependent (it includes disk-derived orphans) and its own test cannot fail on the
denominator; the Angular fetcher seam has the same path rewrite with neither the
rename nor a warning; and an ignored orphan is dropped from the check but not
from the "git-ignored pages not checked" count.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dmealing

CHANGELOG.md

@@ -149,6 +149,96 @@ rather than returning null for an absent name, so a name-keyed lookup would turn
 divergence between the allowlist and the map into an aborted build instead of a skipped
 entry.
 
+### Changed — an attr lookup for a reserved structural keyword now THROWS
+
+`attr("isArray")` could only ever answer `undefined`, and `undefined` is
+indistinguishable from "the author did not set that attribute". Reserved structural
+keywords are NATIVE PROPERTIES: `@isArray` is refused at the load with
+`ERR_RESERVED_ATTR`, so an attribute lookup for one asks a question the metamodel
+forbids anyone to answer.
+
+Found in an adopter's own generator — `f.attr("isArray") === true ? base + "[]" : base`
+— whose generated reference document described **all 31 of that model's array fields as
+scalars**. Its sibling module had used the resolving accessor since the day it was
+written, with a comment naming the trap, and nothing compared the two. ADR-0039 is taught
+in three shipped skills and in that file's own header fourteen lines above the violation:
+prose is not a gate.
+
+A throw rather than a warning, because there is no reading under which the call is
+correct and the fix is one line at the call site. The message names the native accessor
+to use (`.resolvedIsArray()`, `.name`, `.isAbstract`, `children()`, …).
+
+**All four name-taking doors are guarded**, not just the resolving pair: `attr()`,
+`hasAttr()`, `ownAttr()`, `ownHasAttr()` and `ownMetaAttr()`. The own-only accessors ask
+the identical forbidden question and answer it just as silently, and `ownAttr` is a
+documented public accessor an owned generator can reach for — one rule with four doors,
+three left open, is this repo's most-repeated defect shape. `value` stays exempt: an
+`attr` node reads its own typed payload through `ownAttr(RESERVED_KEY_VALUE)`, which is
+the one legitimate reserved-key attr read in the model.
+
+Potentially breaking for a consumer that made such a call — but every such call was
+already returning `undefined`, so the behaviour it depended on was a silent wrong answer.
+No metadata changes; `metamodelVersion` is unchanged. TypeScript only: Python's own-only
+`attr()` and the JVM/C# equivalents carry no guard yet, tracked as follow-up.
+
+### Changed — `useEntityFetcher()` is renamed `useEntityPathFetcher()`
+
+The hook did not merely read the fetcher from context — it returned one that **prepends
+the provider's `baseUrl` to every path**. The name described the read half only, so an
+application-absolute path handed to it produced `<baseUrl>` + that path and a silent 404.
+`useEntityFetcher` remains as a deprecated alias (literally the same function), so nothing
+breaks on upgrade; the rename is what makes the rewrite visible at the call site.
+
+Generated hooks emit ENTITY-relative paths and call the new name. Because the reference
+templates compose `renderHooksFile` / `renderGridHookFile`, an ejected copy picks the
+rename up with no edit.
+
+The shipped surfaces that still taught the old name are corrected in the same release —
+including the `metaobjects-runtime-ui` agent-context skill `meta init` installs into every
+project, which described it as "reads the fetcher from context" with no mention of the
+rewrite. That is the third time a shipped skill has taught something the code had already
+changed, so the two `agent-context-conformance` fixtures move with it.
+
+### Fixed — `outputLayout: "package"` was inert for the form the docs teach
+
+A file may declare its package once at the root (`{"metadata.root": {"package":
+"acme::blog", …}}`) or on each object; the loader treats these as equivalent. Codegen did
+not: every path decision read the object's OWN bare `.package`, which is `undefined` for
+the root-declared form, so `packageToPath(undefined)` returned `""` and every file landed
+flat. With `outputLayout: "package"` the emitted tree was **byte-identical to `flat`** —
+not a broken build, a config key that reads as honoured and does nothing.
+
+It mattered because root-level is the form the product TEACHES: the TypeScript quickstart
+uses it, and across this repo's own metadata it is 614 files against 7 using object-level.
+It survived because the single fixture behind the package-layout golden is one of those 7
+— the gate was written on the rare form, so the common form had never been generated in
+package layout by any test.
+
+**The first fix was itself half-applied**, and that half is fixed here too: the built-in
+`barrel` generator moved to `effectivePackage()` while the four reference/owned copies —
+the ones `meta init` actually scaffolds — kept the bare read and merely gained an unused
+import. Their emitted `index.ts` therefore exported `./Widget` for a file at
+`acme/commerce/Widget.ts`: `TS2307` on a project with nothing wrong with it, and a
+REGRESSION, since before the change the entity files landed flat too and the barrel
+agreed with them. The comment that caused the original defect — which instructed the
+reader to pass `obj.package` "for consistency with the emitter" — was still in place
+stating the opposite of the code, and is rewritten to say why consistency with a wrong
+emitter is not a reason.
+
+The path-level gate could not see any of it: it asserts on EMITTED PATHS, and a barrel's
+path is correct whatever it exports. It now also runs the barrel and requires **every
+export specifier to name a file the same run actually wrote**.
+
+### Fixed — an `increment` primary key was spelled `serial` while migrate wrote IDENTITY
+
+Generated Drizzle emitted `serial`/`bigserial` for a `@generation: increment` key while
+`meta migrate` emitted a `GENERATED BY DEFAULT AS IDENTITY` column — two doors answering
+one declaration with two different DDL forms. Codegen now emits `integer`/`bigint` plus
+`.generatedByDefaultAsIdentity()`, matching migrate. Verified against both ends of
+`codegen-ts`'s declared drizzle-orm peer range, and the PK stays insert-optional (compiled
+with the real TypeScript compiler for `field.int` and `field.long`). The three adopter
+docs that showed `bigserial` as generated output are corrected.
+
 ### Changed — `meta eject` says how your copy compares to the reference
 
 An owned generator is the one artifact ADR-0034 hands an adopter and then never speaks

agent-context/skills/metaobjects-runtime-ui/references/tanstack.md

@@ -34,7 +34,8 @@ rejects and poisons every later install in the project with `ERESOLVE`.
 | Export | Purpose |
 |---|---|
 | `<EntityFetcherProvider fetcher={fetcher} baseUrl="/api">` | supplies the single `EntityFetcher` every generated hook reads, plus the base URL it prepends. `baseUrl` is optional (default `""` = same origin at the root); generated hooks emit entity-relative paths. |
-| `useEntityFetcher()` | reads the fetcher from context (generated hooks call this) |
+| `useEntityPathFetcher()` | reads the fetcher from context and returns one that PREPENDS the provider's `baseUrl` — generated hooks call this, and the path they pass is entity-relative. |
+| `useEntityFetcher()` | deprecated alias of the above. The name said "read the fetcher"; it also rewrites every path, so passing an application-absolute path yields `<baseUrl>` + that path and a silent 404. |
 | `<EntityGrid>` | opinionated TanStack Table component |
 | `<CellRendererProvider>` + `defaultCellRenderers` | renderer overrides keyed by the column's `meta.view` |
 

client/web/packages/runtime-web/src/join-base-url.ts

@@ -2,7 +2,7 @@
  * Join a client base URL to a generated entity-relative path.
  *
  * ONE implementation, shared by both client tiers on purpose. `@metaobjectsdev/tanstack`
- * wraps `useEntityFetcher()` with it and `@metaobjectsdev/angular` wraps the
+ * wraps `useEntityPathFetcher()` with it and `@metaobjectsdev/angular` wraps the
  * `EntityFetcherToken`; implemented separately they would eventually disagree about a
  * trailing slash, and the disagreement would surface as a 404 in one framework only.
  *

docs/features/api-contract.md

@@ -47,7 +47,10 @@ generated):
 
 The fetcher is supplied once via `<EntityFetcherProvider fetcher={fetcher} baseUrl="/api">`
 at the React tree root; every generated hook reads it via
-`useEntityFetcher()` from `@metaobjectsdev/tanstack`.
+`useEntityPathFetcher()` from `@metaobjectsdev/tanstack`, which prepends `baseUrl`
+to the ENTITY-relative path the hook passes it. (`useEntityFetcher()` is a
+deprecated alias — it rewrites paths too, which its name did not say, so handing it
+an application-absolute path produces `<baseUrl>` + that path and a silent 404.)
 
 ## URL grammar
 

docs/features/entities.md

@@ -148,12 +148,12 @@ export const AuthorNames = {
 
 ```ts
 // generated/acme/blog/Author.ts
-import { pgTable, bigserial, varchar } from "drizzle-orm/pg-core";
+import { pgTable, bigint, varchar } from "drizzle-orm/pg-core";
 import { z } from "zod";
 import { AuthorNames } from "./Author.names";
 
 export const author = pgTable(AuthorNames.sources.primary.table, {
-  id:   bigserial(AuthorNames.fields.id.column, { mode: "number" }).primaryKey(),
+  id:   bigint(AuthorNames.fields.id.column, { mode: "number" }).primaryKey().generatedByDefaultAsIdentity(),
   name: varchar(AuthorNames.fields.name.column, { length: 200 }).notNull(),
   bio:  varchar(AuthorNames.fields.bio.column,  { length: 2000 }),
 });

docs/features/field-types.md

@@ -227,7 +227,7 @@ below names no column directly — to read the resolved spelling, open the names
 import { AuthorNames } from "./Author.names";
 
 export const author = pgTable(AuthorNames.sources.primary.table, {
-  id:         bigserial(AuthorNames.fields.id.column, { mode: "number" }).primaryKey(),
+  id:         bigint(AuthorNames.fields.id.column, { mode: "number" }).primaryKey().generatedByDefaultAsIdentity(),
   name:       varchar(AuthorNames.fields.name.column, { length: 200 }).notNull(),
   bio:        varchar(AuthorNames.fields.bio.column, { length: 2000 }),
   priceCents: bigint(AuthorNames.fields.priceCents.column, { mode: "number" }).notNull(),  // currency: minor units

docs/features/relationships.md

@@ -176,7 +176,7 @@ import { AnyPgColumn } from "drizzle-orm/pg-core";
 import { PostNames } from "./Post.names";
 
 export const post = pgTable(PostNames.sources.primary.table, {
-  id:       bigserial(PostNames.fields.id.column, { mode: "number" }).primaryKey(),
+  id:       bigint(PostNames.fields.id.column, { mode: "number" }).primaryKey().generatedByDefaultAsIdentity(),
   title:    varchar(PostNames.fields.title.column, { length: 255 }).notNull(),
   authorId: bigint(PostNames.fields.authorId.column, { mode: "number" })
               .notNull()

docs/ports/typescript-client.md

@@ -56,7 +56,7 @@ a roadmap item: eject the generator and retarget its emit (FR-040).
 |---|---|---|
 | `@metaobjectsdev/runtime-web` | Pure framework-agnostic browser core. Zero React, zero TanStack, zero Node-only deps. | `formatCurrency`, `parseCurrency`, `minorUnitsFor`, `buildFilterQs`, type `EntityFetcher`, type `GridConfig` |
 | `@metaobjectsdev/react` | React-specific runtime (peer-deps on `react`, `react-hook-form`, `@hookform/resolvers`, `zod`). | `useEntityForm`, `<CurrencyInput>`, types `EntityMeta`, `EntityFieldMeta`, `BoundInputProps` |
-| `@metaobjectsdev/tanstack` | TanStack runtime (peer-deps on `@tanstack/react-query`, `@tanstack/react-table`). | `<EntityFetcherProvider>`, `useEntityFetcher`, `<EntityGrid>`, `<CellRendererProvider>`, `defaultCellRenderers` |
+| `@metaobjectsdev/tanstack` | TanStack runtime (peer-deps on `@tanstack/react-query`, `@tanstack/react-table`). | `<EntityFetcherProvider>`, `useEntityPathFetcher`, `<EntityGrid>`, `<CellRendererProvider>`, `defaultCellRenderers` |
 
 ## Codegen packages
 
@@ -111,8 +111,11 @@ below).
 
 ## The `<EntityFetcherProvider>` contract
 
-Every generated hook (React Query) calls `useEntityFetcher()`, which reads
-a single `EntityFetcher` function from React context. The consumer's app
+Every generated hook (React Query) calls `useEntityPathFetcher()`, which reads
+a single `EntityFetcher` function from React context AND returns one that prepends
+the provider's `baseUrl`. The path a generated hook passes it is therefore
+ENTITY-relative, never application-absolute — `useEntityFetcher()` is a deprecated
+alias whose name suggested only the read half. The consumer's app
 supplies the concrete implementation — auth headers, base URL, error
 handling — and the same fetcher serves every entity.
 

examples/advanced-modeling/codegen/generators/barrel.ts

@@ -64,7 +64,7 @@ export const barrel = function barrel(opts?: BarrelOpts): Generator {
         path: "index.ts",
         content: await formatTs(
           renderBarrel(
-            entities.map((e) => ({ name: rc.valueObjectEmittedName(e), package: e.package })),
+            entities.map((e) => ({ name: rc.valueObjectEmittedName(e), package: effectivePackage(e) })),
             rc.extStyle,
             rc.selfTarget,
             rc.entityModuleTarget,

examples/showcase/codegen/generators/barrel.ts

@@ -64,7 +64,7 @@ export const barrel = function barrel(opts?: BarrelOpts): Generator {
         path: "index.ts",
         content: await formatTs(
           renderBarrel(
-            entities.map((e) => ({ name: rc.valueObjectEmittedName(e), package: e.package })),
+            entities.map((e) => ({ name: rc.valueObjectEmittedName(e), package: effectivePackage(e) })),
             rc.extStyle,
             rc.selfTarget,
             rc.entityModuleTarget,