refactor: the simplifier pass, and two things it caught that the review did not

Four cleanup agents over this session's twelve commits. Two of their findings were
correctness, not tidiness, and both were mine:

**The ejectable copy of the names generator still hardcoded `fragment: true`.**
`src/reference/names.ts` is what `meta init` copies into an adopter's repo, and it is
otherwise character-for-character the generator I had just fixed. Its byte-identical gate
could not see the divergence — that gate runs `runGen` unscoped, so pass 1 always emits
the TPH base and pass 2 breaks on `emitted.has(key)` before the flag is read. The bug is
reachable only under `meta gen --entities <Subtype>`, which the gate never exercises.

Fixed at the depth that makes it unreachable rather than by mirroring one line:
`renderNamesDecl` now DERIVES the shape from the object, so `fragment` says only "this is
an ancestor render". Every `fragment: true` already on disk in an adopter's ejected copy
becomes correct with no edit, and no caller can get it wrong again. Mirroring the line
would also have forced a VALUE import from `@metaobjectsdev/metadata` into an ejected
file, which is the dual-physical-copy hazard CLAUDE.md warns about.

**I shipped a false claim while fixing a false claim.** The JSDoc I corrected two commits
ago says "htmlType, placeholder and helpText are NOT emitted". `htmlType` IS emitted —
derived from the view subtype; only the `@htmlType` attribute OVERRIDE was removed. The
golden snapshots updated in that same commit carry `htmlType: "number"` fifteen lines
below the claim. Corrected, and it says which of the two mechanisms went away.

The rest is tidying, each agreed by at least two agents:

- `servedPath(entity, apiPrefix)` in `api-surface.ts` replaces three open-coded copies of
  `${apiPrefix}${restPath(obj)}`. Three doors composing one address is the defect class
  these commits keep fixing; leaving a third copy behind while fixing the second was not
  defensible.
- The new C# `Escape` was a verbatim copy of `Fr010FieldMapping.CSharpStringLiteral`, the
  sixth escaper in that assembly. Deleted; the allocation-free fast path moved INTO the
  shared helper, so its three existing callers get it too.
- `declaresNamesContent` dropped a dead `typeof obj.ownFields !== "function"` duck-type
  check; `namesArtifactSuperOf` narrows with the exported `isMetaObject` guard instead of
  `as MetaObject`, which is what CLAUDE.md requires.
- The effective-children `claimed` set became a flag array in TS and Python, mirroring the
  C# port: the length is known, this is the memoized path walked for every node, and it
  drops a hash lookup per element plus a closure/generator frame per own child.
- A dead `resourcePath` import, a recomputed `memberDepth`, and a `"source"` literal with
  a double cast where `isMetaSource` narrows.

Skipped, deliberately: de-duplicating the test harnesses in four files (three agents
flagged it; it is churn across passing tests), and folding `ApiModelContext`'s positional
threading into a resolved struct (a wider refactor than this pass warrants). Both are
recorded here rather than argued with.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UcDcQmAVYzYjkVGVj23mt4

Author: dmealing

examples/showcase/.metaobjects/.gen-state/.hashes.json

@@ -10,7 +10,7 @@
   "__init__.py": "daa04cec586768866d0996c779f62073e6773fe63750ff668327991fac2fd0f5",
   "generated/ts/Subscriber.queries.ts": "843e21d8ed84ecead64870b980dfa3156dd2f360ade1f1d2693a5f04bde0fb3c",
   "generated/ts/Subscriber.routes.ts": "05d57884708ed78bdad9d69744b1685bc7a310a988aec2edd2830b53b68b3315",
-  "generated/ts/Subscriber.ts": "abfb328f5eacc3d1c1ea890267dc7af8dfe2656592e33d032df14c76b3ca3e19",
+  "generated/ts/Subscriber.ts": "b215a36de8a7eb3845b6b71daf72e2d4f54897441f25dc96d9fe0181ad758d87",
   "generated/ts/SubscriberBlurbPayload.ts": "613a80a6c0ce7e967f84f7af3c587a3c6f04434a67cea838344217ab6d132fb9",
   "generated/ts/index.ts": "b9f04c67786b5eec1aa493958d9843b86a58406228fcfc85634559fc4b2cbfa6",
   "generated/ts/prompts.ts": "9cd69070c5b9c1f4b1200422858ef34488c2e8aa8ea5339714629a8de72c81cb",

examples/showcase/generated/ts/Subscriber.ts

@@ -61,15 +61,16 @@ export const SubscriberInsertPreservingSchema = z.object({
  *
  * Use these instead of magic strings so TS catches typos and refactors stay
  * coherent. Each non-dollar-prefixed key is a per-field object carrying
- * name, label, view, and the RHF-shaped validation rules derived from the
- * field's validator children.
+ * name, label, view, an htmlType where the field's view maps to one, and the
+ * RHF-shaped validation rules derived from the field's validator children.
  *
- * htmlType, placeholder and helpText are NOT emitted — no provider registers
- * an attribute for them, so nothing here could derive one. useEntityForm
- * still honours all three if you add them: this file is generated, hand edits
- * inside it survive regeneration through the three-way merge, and the
- * consumers read this const rather than the metadata. That is the intended
- * way to set them.
+ * placeholder and helpText are NOT emitted — no provider registers an attribute
+ * for them, so nothing here could derive one. (htmlType is emitted, but derived
+ * from the view subtype; the @htmlType override was removed for the same reason.)
+ * useEntityForm still honours placeholder if you add it: this file is generated,
+ * hand edits inside it survive regeneration through the three-way merge, and the
+ * consumers read this const rather than the metadata. That is the intended way
+ * to set it.
  *
  * Typical usage with the metaobjects React form helper:
  *

examples/showcase/site-payload.json

@@ -214,8 +214,19 @@ public static bool HasXmlText(MetaData field) =>
         (field.Attr(MetaObjects.Template.TemplateConstants.FIELD_ATTR_XML_TEXT) is string s &&
          s.Equals("true", StringComparison.OrdinalIgnoreCase));
 
-    /// <summary>Escape a value for embedding inside a C# double-quoted string literal.</summary>
-    public static string CSharpStringLiteral(string value)
+    private static readonly char[] CSharpEscapeChars = { '\\', '"', '\t', '\n', '\r' };
+
+    /// <summary>
+    /// Escape a value for embedding inside a C# double-quoted string literal.
+    /// <para>Scans before it builds: the names generator calls this two-to-four times per
+    /// member of every entity, and virtually every value — "object", "entity", a field
+    /// name, a snake_case column — contains none of these. <c>IndexOfAny</c> is vectorized
+    /// and allocates nothing, so the common case costs no allocation at all.</para>
+    /// </summary>
+    public static string CSharpStringLiteral(string value) =>
+        value.IndexOfAny(CSharpEscapeChars) < 0 ? value : CSharpStringLiteralSlow(value);
+
+    private static string CSharpStringLiteralSlow(string value)
     {
         var sb = new System.Text.StringBuilder(value.Length + 4);
         foreach (char c in value)

server/csharp/MetaObjects.Codegen/Generators/Fr010FieldMapping.cs

@@ -102,26 +102,7 @@ protected override EmittedFile GenerateOne(MetaObject entity, GenContext ctx) =>
     /// identifier and may hold either character.
     /// </summary>
     private static Member Str(string name, string value, string nodePath) =>
-        new(name, $"const string {name} = \"{Escape(value)}\";", nodePath);
-
-    /// <summary>C# string-literal escaping for an author-supplied value.</summary>
-    private static string Escape(string value)
-    {
-        var sb = new System.Text.StringBuilder(value.Length + 8);
-        foreach (var c in value)
-        {
-            switch (c)
-            {
-                case '\\': sb.Append("\\\\"); break;
-                case '"': sb.Append("\\\""); break;
-                case '\n': sb.Append("\\n"); break;
-                case '\r': sb.Append("\\r"); break;
-                case '\t': sb.Append("\\t"); break;
-                default: sb.Append(c); break;
-            }
-        }
-        return sb.ToString();
-    }
+        new(name, $"const string {name} = \"{Fr010FieldMapping.CSharpStringLiteral(value)}\";", nodePath);
 
     /// <summary>
     /// Every constant an artifact declares, in emission order, grouped so the emitter can

server/csharp/MetaObjects.Codegen/Generators/NamesGenerator.cs

@@ -511,7 +511,10 @@ private List<MetaData> EffectiveChildren(HashSet<MetaData> visited)
         // child is deferred so it cannot be matched later — and this closes the branch it
         // left open. The shape is a write-through entity (two unnamed source.rdb children)
         // whose base ALSO declares a source: its own primary was silently dropped.
-        var claimed = new HashSet<int>();
+        // A flag array, not a HashSet: `result` does not grow until after this loop, so the
+        // length is known, and this is the memoized effective-children path walked for every
+        // node. One allocation, index access instead of hashing, no boxing.
+        var claimed = new bool[result.Count];
         foreach (var ownChild in _children)
         {
             // Find the index in result that has the same (type, name). An explicit loop
@@ -520,7 +523,7 @@ private List<MetaData> EffectiveChildren(HashSet<MetaData> visited)
             int idx = -1;
             for (int i = 0; i < result.Count; i++)
             {
-                if (!claimed.Contains(i) && result[i].Type == ownChild.Type
+                if (!claimed[i] && result[i].Type == ownChild.Type
                     && result[i].Name == ownChild.Name)
                 {
                     idx = i;
@@ -531,7 +534,7 @@ private List<MetaData> EffectiveChildren(HashSet<MetaData> visited)
             {
                 // Replace the super child with our own (in-place override).
                 result[idx] = ownChild;
-                claimed.Add(idx);
+                claimed[idx] = true;
             }
             else
             {

server/csharp/MetaObjects/Meta/MetaData.cs

@@ -96,7 +96,7 @@
     strip_package,
     to_snake_case,
 )
-from metaobjects.shared.base_types import TYPE_IDENTITY, TYPE_INDEX
+from metaobjects.shared.base_types import TYPE_FIELD, TYPE_IDENTITY, TYPE_INDEX
 from metaobjects.source_resolution import primary_rdb_source
 
 #: The nodes whose DATABASE index name this module carries.
@@ -238,6 +238,12 @@ def _field_consts(field: MetaData, column: str) -> list[_Const]:
     ]
 
 
+#: The node types a names module carries. A frozenset of module-level constants rather
+#: than an inline tuple: an inline one is rebuilt on every element compared, because
+#: CPython cannot fold a tuple of globals.
+_NAMES_CONTENT_TYPES = frozenset({TYPE_FIELD, TYPE_IDENTITY, TYPE_INDEX})
+
+
 def declares_names_content(entity: MetaObject) -> bool:
     """Whether ``entity`` DECLARES anything a names module carries.
 
@@ -254,10 +260,7 @@ def declares_names_content(entity: MetaObject) -> bool:
     declares, not what it can see. An inherited key belongs to the ancestor that
     declared it and is reached through that ancestor's module.
     """
-    return bool(
-        entity.own_fields()
-        or [c for c in entity.own_children() if c.type in (TYPE_IDENTITY, TYPE_INDEX)]
-    )
+    return any(c.type in _NAMES_CONTENT_TYPES for c in entity.own_children())
 
 
 def names_artifact_super_of(entity: MetaObject) -> MetaObject | None:

server/python/src/metaobjects/codegen/generators/names_generator.py

@@ -242,18 +242,21 @@ def _effective_children_inner(
             # branch it left open: the same write-through shape, but with the BASE also
             # declaring a source, so the first own source takes the replace branch.
             append_queue: list[MetaData] = []
-            claimed: set[int] = set()
+            # A flag array, not a set: `result` does not grow until after this loop, so
+            # the length is known, and this is the memoized effective-children path walked
+            # for every node. Also drops the per-own-child generator frame `next()` built.
+            claimed = bytearray(len(result))
             for own in self._children:
-                idx = next(
-                    (i for i, c in enumerate(result)
-                     if i not in claimed and c.type == own.type and c.name == own.name),
-                    None,
-                )
+                idx = None
+                for i, c in enumerate(result):
+                    if not claimed[i] and c.type == own.type and c.name == own.name:
+                        idx = i
+                        break
                 if idx is None:
                     append_queue.append(own)
                 else:
                     result[idx] = own
-                    claimed.add(idx)
+                    claimed[idx] = 1
             result.extend(append_queue)
         return result
 

server/python/src/metaobjects/meta/meta_data.py

@@ -22,7 +22,7 @@ import type { MetaObject } from "@metaobjectsdev/metadata";
 import { isAbstract } from "./instance-artifacts.js";
 import { isProjection } from "./projection/projection-detector.js";
 import { hasAnyRdbSource, hasWritableRdbSource } from "./source-detect.js";
-import { resourcePath } from "./templates/entity-ui-descriptor.js";
+import { resourcePath, restPath } from "./templates/entity-ui-descriptor.js";
 import {
   declaresTphDiscriminator,
   isTphSubtype,
@@ -59,6 +59,21 @@ export function servesWriteApi(entity: MetaObject): boolean {
 // have to care that the composition moved.
 export { restPath } from "./templates/entity-ui-descriptor.js";
 
+/**
+ * The address the generated routes actually SERVE an object at: the mount prefix plus the
+ * object's REST path.
+ *
+ * One function, because getting this wrong is the defect it exists to prevent, twice over.
+ * `agent/ui.md` documented `/authors` for routes mounted at `/api/authors`; the API
+ * reference did the same, separately, in two more places — three doors composing one
+ * address, each free to drift from the others. `templates/routes-file-hono.ts` and
+ * `routes-file.ts` compose the same thing into GENERATED code and remain the runtime
+ * authority; this is the documentation side mirroring them.
+ */
+export function servedPath(entity: MetaObject, apiPrefix: string): string {
+  return `${apiPrefix}${restPath(entity)}`;
+}
+
 /**
  * True when a FORM is generated for this object.
  *

server/typescript/packages/codegen-ts/src/api-surface.ts

@@ -43,7 +43,7 @@ import {
 } from "@metaobjectsdev/metadata";
 import type { MetaData, MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
 import { GENERATED_HEADER } from "../constants.js";
-import { hasGeneratedForm, restPath, servesReadApi } from "../api-surface.js";
+import { hasGeneratedForm, restPath, servedPath, servesReadApi } from "../api-surface.js";
 import {
   buildEntityUiDescriptor,
   type UiFieldDescriptor,
@@ -121,7 +121,7 @@ function flag(value: unknown): string {
  * is deliberately no form"; asking the endpoint question announced one for every base.
  */
 function endpointLine(obj: MetaObject, root: MetaRoot, apiPrefix: string): string {
-  const endpoint = `${apiPrefix}${restPath(obj)}`;
+  const endpoint = servedPath(obj, apiPrefix);
   if (hasGeneratedForm(obj)) return `Endpoint \`${endpoint}\`.`;
   // `isTphDiscriminatorBase`, which requires at least one CONCRETE subtype — the same
   // predicate `routes-file.ts` switches on. `@discriminator` with no subtype yet is a