@voxgig/sdkgen 3.5.1 → 3.7.0

package/project/.sdk/tm/ts/test/utility/PrimaryUtility.test.ts

@@ -35,7 +35,7 @@ describe('PrimaryUtility', async () => {
   // (.sdk/test/primary/<name>.aontu carries a PENDING header). Everything
   // else MUST contribute cases.
   const PENDING = new Set([
-    'fetcher', 'makeFetchDef', 'makePoint', 'makeResult',
+    'fetcher', 'makeFetchDef', 'makeResult',
     'featureAdd', 'featureHook', 'featureInit',
   ])
 
@@ -279,22 +279,15 @@ describe('PrimaryUtility', async () => {
   })
 
 
-  test('makePoint-single', () => {
-    const ctx = makeCtx()
-    const point = {
-      parts: ['items', '{id}'],
-      args: { params: [] },
-      params: [],
-      alias: {},
-      select: {},
-      active: true,
-      transform: { req: undefined, res: undefined },
-    }
-    ctx.op.points = [point]
-
-    const result = utility.makePoint(ctx)
-    ok(!(result instanceof Error))
-    equal(ctx.point, point)
+  // Was one hand-written case (the single-point path) covering one of this
+  // utility's seven branches, which is how the corpus fixture came to be
+  // marked deferred as "needs a real client". It does not: Context rebuilds
+  // `op` from opname + entity + config, and `options` can be supplied
+  // literally, so allow.op, the empty-points error, exist-selection,
+  // $action selection and the invalid-$action error are all expressible.
+  // Driven from the corpus now, so every port asserts the same branches.
+  test('makePoint-basic', async () => {
+    await runsection('makePoint', utility.makePoint)
   })
 
 

package/project/.sdk/tm/zig/core/utility.zig

@@ -521,6 +521,29 @@ pub fn make_options_util(ctx: *Context) Value {
 // make_point (gotcha #2: rbac PrePoint short-circuit)
 // ============================================================================
 
+// How many path segments a point has.
+fn point_parts_len(point: Value) i64 {
+    const parts = h.getp(point, "parts");
+    if (parts != .array) return 0;
+    return @intCast(parts.array.data.items.len);
+}
+
+// Does this point's path end in a parameter? A record route ends in the
+// record's identifier (/boards/{id}); a cross-reference that also returns the
+// entity ends in the relationship's name (/posts/{id}/author). That, then
+// fewest segments, is what tells the entity's own route from a
+// cross-reference. The same rule runs at generation time, in
+// helpers/opShape.ts — both sides must move together.
+fn point_terminal_param(point: Value) bool {
+    const parts = h.getp(point, "parts");
+    if (parts != .array) return false;
+    const items = parts.array.data.items;
+    if (0 == items.len) return false;
+    const last = items[items.len - 1];
+    if (last != .string) return false;
+    return 0 < last.string.len and '{' == last.string[0];
+}
+
 pub fn make_point_util(ctx: *Context) E!Value {
     if (ctx.out_get("point")) |ov| {
         switch (ov) {
@@ -560,10 +583,11 @@ pub fn make_point_util(ctx: *Context) E!Value {
         const selector: Value = if (std.mem.eql(u8, op.input, "data")) ctx.data else ctx.mtch;
 
         var point: Value = h.vnull();
+        var matched = false;
         var i: i64 = 0;
         while (i < plen) : (i += 1) {
-            point = h.get_elem(points, h.vnum(i), h.vnull());
-            const select_def = h.to_map(h.getp(point, "select"));
+            const cand = h.get_elem(points, h.vnum(i), h.vnull());
+            const select_def = h.to_map(h.getp(cand, "select"));
             var found = true;
 
             if (!h.is_noval(selector) and !h.is_noval(select_def)) {
@@ -589,7 +613,46 @@ pub fn make_point_util(ctx: *Context) E!Value {
                 if (!h.veq(req_action, select_action)) found = false;
             }
 
-            if (found) break;
+            if (found) {
+                point = cand;
+                matched = true;
+                break;
+            }
+        }
+
+        // select.exist can list more than the params needed to pick a point
+        // (for /boards/{id} it is Trello's 17 optional query-includes), so a
+        // plain {id} call matches NOTHING. Fall back to the entity's own
+        // route rather than whichever point came last.
+        if (!matched) {
+            // A request naming an action reaches here only because that
+            // action's own point failed its exist test, so it is unbuildable
+            // whatever we pick. Refuse it BEFORE choosing a fallback: the
+            // guard below compares the chosen point's $action and would wave
+            // the request through whenever the fallback lands on the action
+            // point itself.
+            const unmatched_action = h.getp(reqselector, "$action");
+            if (!h.is_noval(unmatched_action)) {
+                return ctx.fail("point_action_invalid", fmt("Operation \"{s}\" action \"{s}\" is not valid.", .{ op.name, h.stringify(unmatched_action) }));
+            }
+
+            // A terminal parameter marks a record route (/boards/{id}); a
+            // cross-reference ends in the relationship's name
+            // (/posts/{id}/author). Failing that, the shallower path wins.
+            // The same rule runs at generation time, in helpers/opShape.ts —
+            // both sides must move together.
+            point = h.get_elem(points, h.vnum(0), h.vnull());
+            var j: i64 = 0;
+            while (j < plen) : (j += 1) {
+                const cand = h.get_elem(points, h.vnum(j), h.vnull());
+                const cand_term = point_terminal_param(cand);
+                const best_term = point_terminal_param(point);
+                if (cand_term != best_term) {
+                    if (cand_term) point = cand;
+                } else if (point_parts_len(cand) < point_parts_len(point)) {
+                    point = cand;
+                }
+            }
         }
 
         const req_action = h.getp(reqselector, "$action");

package/project/sdkgen-package.json

@@ -3,7 +3,7 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "provides": {
     "target": [
       "c",
@@ -15,7 +15,6 @@
       "go",
       "go-cli",
       "go-mcp",
-      "haskell",
       "java",
       "js",
       "kotlin",

package/src/cmp/AgentGuideTop.ts

@@ -80,6 +80,24 @@ package (other languages). Each target's guide documents its features.
       Content(`**Entities** (${entities.length}): `)
       Content(entities.map((e: any) => `\`${e.Name || e.name}\``).join(', ') + `.
 
+`)
+    }
+
+    // Station paragraph (station design §9.4), only when the model
+    // carries the feature: an agent working on this repo should know
+    // the runtime story without leaving AGENTS.md.
+    if (features.some((f: any) => 'station' === f.name)) {
+      Content(`**Station**: this SDK is a
+[voxgig/station](https://github.com/voxgig/station) plugin (the
+\`station\` feature, off by default). Bound to an open \`Station\`,
+the credential is resolved by sekreto under the plugin's secret name
+and injected at the transport seam — \`options()\` and
+\`prepare()\` output hold only a placeholder, so both are safe to
+inspect and log. \`station.tap(...)\`/\`station.events()\` show live
+traffic; \`station.plugins()\` lists descriptors. See the "Use with
+Station" README section and \`src/feature/station/\` (or the
+target's feature container) for the generated adapter.
+
 `)
     }
 

package/src/cmp/ExternalTarget.ts

@@ -88,7 +88,7 @@ const ExternalTarget = cmp(function ExternalTarget(props: any) {
     names(target, target.name)
 
     if (phaseActive('entity')) {
-      each(entity, (entity: any) => {
+      each(entity).filter((entity: any) => entity.active).map((entity: any) => {
         names(entity, entity.name)
         Entity({ target, entity })
       })

package/src/cmp/Readme.ts

@@ -6,6 +6,7 @@ import { ReadmeIntro } from './ReadmeIntro'
 import { ReadmeInstall } from './ReadmeInstall'
 import { ReadmeQuick } from './ReadmeQuick'
 import { ReadmeErrors } from './ReadmeErrors'
+import { ReadmeStation } from './ReadmeStation'
 import { ReadmeModel } from './ReadmeModel'
 import { ReadmeOptions } from './ReadmeOptions'
 import { ReadmeEntity } from './ReadmeEntity'
@@ -24,6 +25,7 @@ const Readme = cmp(function Readme(props: any) {
     ReadmeIntro({ target })
     ReadmeInstall({ target })
     ReadmeQuick({ target })
+    ReadmeStation({ target })
     ReadmeErrors({ target })
     ReadmeHowto({ target })
     ReadmeModel({ target })

package/src/cmp/ReadmeStation.ts

@@ -0,0 +1,69 @@
+
+import { cmp, Content } from 'jostraca'
+
+import {
+  KIT,
+  getModelPath
+} from '../types'
+
+import { envName } from '../helpers/packageMeta'
+
+
+// The "Use with Station" README section (station design §9.4): rendered
+// ONLY when the project's model carries the station feature (installed
+// via `package add @voxgig/sdkgen-station`) — a project without it sees
+// nothing. Documents the binding forms and the secret name; store
+// configuration is sekreto's documentation, deliberately not restated
+// here (one canonical source).
+
+// Targets where station.connect(SDK) is the idiomatic binding; everything
+// else uses inverted binding through the SDK's own constructor.
+const CONNECT_TARGETS = ['ts', 'js', 'py', 'rb', 'php', 'lua', 'perl']
+
+const ReadmeStation = cmp(function ReadmeStation(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const features = getModelPath(model, `main.${KIT}.feature`,
+    { only_active: false, required: false }) || {}
+  const station = Object.values(features)
+    .find((f: any) => 'station' === f?.name)
+  if (null == station) { return }
+
+  const env = envName(model)
+  const secretname = env.toLowerCase() + '.apikey'
+  const connect = CONNECT_TARGETS.includes(target.name)
+
+  Content(`
+## Use with Station
+
+This SDK ships as a [voxgig/station](https://github.com/voxgig/station)
+plugin: bind it to a local \`Station\` and outbound configuration,
+credentials, and observability move to one place. The feature is
+present but **off by default** — nothing changes until you bind.
+
+${connect
+  ? `Bind by passing the SDK class to the station:
+
+1. \`station = Station.open()\` — profile, env, and proxy all defaulted.
+2. \`client = station.connect(${model.const.Name}SDK)\` — replaces direct
+   construction.`
+  : `Bind through the constructor this SDK already has (inverted
+binding): open a station, then construct with station-built options —
+\`station.options()\` merges the handle, the activation entry, and the
+correct feature order into the plain options the constructor accepts.`}
+
+The credential comes from [sekreto](https://github.com/voxgig/sekreto)
+under the name \`${secretname}\` — by default the \`${env}_APIKEY\`
+environment variable this README already documents, unchanged. Point a
+profile in \`station.json\` at a vault later and application code does
+not change; sekreto's own documentation covers the stores. The key
+stays out of \`options()\` and \`prepare()\` output; \`station.tap(...)\`
+shows live traffic.
+`)
+})
+
+
+export {
+  ReadmeStation
+}

package/src/helpers/naming.ts

@@ -112,17 +112,67 @@ function isRbCoreConstant(Name: string): boolean {
 }
 
 
+// RUBY SDK-OWNED CONSTANTS — the OTHER half of "already taken".
+//
+// `RB_CORE_CONSTANTS` guards names the LANGUAGE owns. This guards names the
+// GENERATED SCAFFOLDING claims for itself, which is a distinct hazard and the
+// one that stayed open: an entity named `Runner` produced `class Runner` in
+// `<Sdk>_types.rb`, and the generated harness then does
+//
+//   Runner = ProjectNameTestRunner        # tm/rb/test/runner.rb
+//
+// so inside the test process the entity TYPE silently *is* the test runner.
+// Ruby warns (`already initialized constant Runner`) and carries on, which is
+// why it survived: nothing in the suite exercises the type, so `rb` passed.
+// Reported on gitlab-sdk, which has a `Runner` entity (issue #64).
+//
+// EVERYTHING SHARES ONE NAMESPACE HERE, unlike swift. Swift's Tests module is
+// separate from the SDK module, so `SWIFT_SDK_TYPES` can exclude test-only
+// declarations. Ruby has no such split — the types file and the test files are
+// all required into one process when the suite runs, which is exactly the
+// reported symptom — so test-declared names belong in this set.
+//
+// PREFIXED DECLARATIONS ARE DELIBERATELY ABSENT. `ProjectNameUtility` and
+// friends substitute to `<Sdk>Utility`, and a generated entity type is the
+// bare entity name, so those cannot collide. Only the UNPREFIXED declarations
+// are reachable.
+//
+// `rb-sdk-constants.test.ts` re-derives this list from the templates AND the
+// components and fails on drift — the same discipline as
+// `swift-sdk-types.test.ts`, and for the same reason: the first cut of that
+// list was collected by hand and missed three names, one of them declared by
+// a component rather than a template.
+const RB_SDK_CONSTANTS = new Set<string>([
+  // module-level aliases the test harness defines for convenience
+  'Helpers', 'Runner', 'Vs',
+  // vendored struct library and its test scaffolding
+  'StructRunner', 'StructTestClient', 'StructUtilityTest', 'VoxgigStruct',
+  'STRUCT_TEST_JSON_FILE',
+  // the generated/templated test classes
+  'ExistsTest', 'FeatureTest', 'NetsimTest', 'PipelineTest',
+  'PrimaryUtilityTest', 'ReadmeExamplesTest', 'TestHookFeature',
+  'TestInitFeature',
+])
+
+
+// Does `Name` collide with a constant the generated Ruby SDK already declares?
+function isRbSdkConstant(Name: string): boolean {
+  return RB_SDK_CONSTANTS.has(Name)
+}
+
+
 // A top-level-safe Ruby constant name for a generated type: the name
-// unchanged, unless Ruby core already owns it, in which case `Type` is
-// appended (`File` -> `FileType`). Applied ONLY to the bare entity data type
-// — the per-op type names always carry a suffix (`FileCreateData`,
-// `FileLoadMatch`), which no core constant matches.
+// unchanged, unless it is ALREADY TAKEN — by Ruby core, or by the SDK's own
+// scaffolding — in which case `Type` is appended (`File` -> `FileType`,
+// `Runner` -> `RunnerType`). Applied ONLY to the bare entity data type: the
+// per-op type names always carry a suffix (`FileCreateData`,
+// `FileLoadMatch`), which nothing in either set matches.
 //
 // The entity ACCESSOR keeps its original name (`client.File(...)`): methods
 // and constants live in separate namespaces in Ruby, so the accessor never
 // collided and the public surface is unchanged.
 function rbSafeTypeName(Name: string): string {
-  return isRbCoreConstant(Name) ? Name + 'Type' : Name
+  return isRbCoreConstant(Name) || isRbSdkConstant(Name) ? Name + 'Type' : Name
 }
 
 
@@ -166,6 +216,8 @@ const SWIFT_SDK_TYPES = new Set<string>([
   'OrderedDictionary', 'Sentinel', 'Value', 'VList', 'VMap', 'WalkApply',
   // function/callback aliases
   'FetcherFunc', 'Formatter', 'NativeCall0', 'NativeRef', 'SystemFetch',
+  // transport plumbing
+  'ManualRedirectDelegate',
   // features
   'AuditFeature', 'BaseFeature', 'CacheFeature', 'ClienttrackFeature',
   'DebugFeature', 'IdempotencyFeature', 'LogFeature', 'MetricsBucket',
@@ -195,6 +247,116 @@ function swiftSafeTypeName(Name: string): string {
 }
 
 
+// PHP RESERVED WORDS THAT CANNOT BE A CLASS NAME — a fifth hazard, and the
+// only one of the five where the check must be CASE-INSENSITIVE.
+//
+// PHP's grammar refuses a reserved word where a class name is expected, so a
+// spec with a `Namespace` entity emitted a file that does not parse at all:
+//
+//   /** Namespace entity data model. */
+//   class Namespace
+//   {
+//   }
+//   -> PHP Parse error: syntax error, unexpected token "namespace",
+//                       expecting identifier
+//
+// Found on gitlab-sdk (issue #64), and LATENT in the worst way: `types/` is on
+// the composer classmap but nothing references the file, so PHP never loads it
+// and the php lane passed for as long as the target has existed. It would
+// fatal the moment anything required it, and the documented type is unusable
+// either way.
+//
+// CASE-INSENSITIVITY IS THE WHOLE TRICK. Class and function names in PHP are
+// case-insensitive, so `Namespace`, `NAMESPACE` and `namespace` are one
+// identifier — and the generated name is PascalCase while the reserved word is
+// lowercase. A case-sensitive `Set.has('Namespace')` against a lowercase list
+// therefore matches NOTHING and reopens the bug silently. Entries are stored
+// folded, and the lookup folds too.
+//
+// Taken from the PHP manual's reserved-words tables wholesale rather than
+// grown one collision at a time: the list is fixed by the language, and
+// picking from it by hand is how the second `Namespace` gets shipped.
+const PHP_RESERVED_TYPES = new Set<string>([
+  // keywords
+  'abstract', 'and', 'array', 'as', 'break', 'callable', 'case', 'catch',
+  'class', 'clone', 'const', 'continue', 'declare', 'default', 'do', 'echo',
+  'else', 'elseif', 'empty', 'enddeclare', 'endfor', 'endforeach', 'endif',
+  'endswitch', 'endwhile', 'enum', 'eval', 'exit', 'extends', 'final',
+  'finally', 'fn', 'for', 'foreach', 'function', 'global', 'goto', 'if',
+  'implements', 'include', 'include_once', 'instanceof', 'insteadof',
+  'interface', 'isset', 'list', 'match', 'namespace', 'new', 'or', 'print',
+  'private', 'protected', 'public', 'readonly', 'require', 'require_once',
+  'return', 'static', 'switch', 'throw', 'trait', 'try', 'unset', 'use',
+  'var', 'while', 'xor', 'yield',
+  // compile-time constants
+  '__class__', '__dir__', '__file__', '__function__', '__line__',
+  '__method__', '__namespace__', '__trait__',
+  // reserved as type names / cannot be declared as a class
+  'bool', 'false', 'float', 'int', 'iterable', 'mixed', 'never', 'null',
+  'numeric', 'object', 'parent', 'resource', 'self', 'string', 'true', 'void',
+])
+
+
+// Does `Name` collide with a word PHP reserves, ignoring case as PHP does?
+function isPhpReservedType(Name: string): boolean {
+  return PHP_RESERVED_TYPES.has(String(Name).toLowerCase())
+}
+
+
+// A declarable PHP class name for a generated type: unchanged, unless PHP
+// reserves the word, in which case `Type` is appended (`Namespace` ->
+// `NamespaceType`). Mirrors rbSafeTypeName and swiftSafeTypeName deliberately
+// — same suffix, same "only rename on an actual collision" rule, so every SDK
+// that does not collide is byte-identical to before.
+//
+// Applied ONLY to the bare entity data class. Per-op type names already carry
+// their own suffix (`NamespaceLoadData`, `NamespaceCreateData`), which no
+// reserved word matches, and the entity ACCESSOR is a method rather than a
+// class — PHP resolves those separately — so the public surface is unchanged.
+function phpSafeTypeName(Name: string): string {
+  return isPhpReservedType(Name) ? Name + 'Type' : Name
+}
+
+
+// TypeScript GLOBAL TYPE NAMES — a fourth hazard, same shape as the Ruby and
+// Swift ones above but for TS/JS builtins, which are in scope everywhere
+// with no import. An entity named `Record` emitted `export interface Record
+// {...}` and canonToType's own generic-object mapping (`Record<string,
+// any>`) then resolved to that flat interface INSIDE THE SAME FILE instead
+// of the builtin: `error TS2315: Type 'Record' is not generic` — on a
+// field of the `Record` entity itself.
+//
+// Utility types (`Record`, `Partial`, ...) and common global constructors
+// (`Array`, `Map`, `Promise`, ...) that a REST entity name plausibly lands
+// on. Mirrors RB_CORE_CONSTANTS / SWIFT_SDK_TYPES: only real builtins are
+// listed, so a non-colliding SDK stays byte-identical to before.
+const TS_RESERVED_TYPES = new Set<string>([
+  // utility types
+  'Record', 'Partial', 'Required', 'Readonly', 'Pick', 'Omit', 'Exclude',
+  'Extract', 'NonNullable', 'Parameters', 'ReturnType', 'InstanceType',
+  'Awaited', 'ConstructorParameters',
+  // global constructors / builtins
+  'Array', 'Object', 'Map', 'Set', 'WeakMap', 'WeakSet', 'Date', 'Error',
+  'Function', 'Promise', 'RegExp', 'String', 'Number', 'Boolean', 'Symbol',
+  'ArrayBuffer', 'Proxy', 'Reflect', 'JSON', 'Math',
+])
+
+
+// Does `Name` collide with a TS/JS global type?
+function isTsReservedType(Name: string): boolean {
+  return TS_RESERVED_TYPES.has(Name)
+}
+
+
+// A collision-free TS type name for a generated type: unchanged, unless it
+// shadows a TS/JS global, in which case `Type` is appended (`Record` ->
+// `RecordType`). Mirrors rbSafeTypeName / swiftSafeTypeName. Applied ONLY
+// to the bare entity data type, for the same reason as both of those.
+function tsSafeTypeName(Name: string): string {
+  return isTsReservedType(Name) ? Name + 'Type' : Name
+}
+
+
 // Is `name` a reserved word (an illegal identifier) in the target language?
 function isReservedName(name: string, lang: string): boolean {
   const set = RESERVED[lang]
@@ -328,9 +490,14 @@ export {
   phpEntityAccessor,
   entityCacheField,
   isRbCoreConstant,
+  isRbSdkConstant,
   rbSafeTypeName,
   isSwiftSdkType,
   swiftSafeTypeName,
+  isPhpReservedType,
+  phpSafeTypeName,
+  isTsReservedType,
+  tsSafeTypeName,
   jsProp,
   jsOptProp,
   jsKey,

package/src/helpers/opShape.ts

@@ -189,6 +189,72 @@ function entityPath(entity: any): string {
 }
 
 
+// The entity's OWN endpoint among an op's points.
+//
+// The other notion of canonical above — "not a `$action` route" — separates a
+// folded-in custom action from the real op. This one separates the entity's
+// own route from a CROSS-REFERENCE: another resource's route that happens to
+// return this entity (`/notifications/{id}/board` for a board). Both are
+// plain GETs with no `$action`, so the path itself is all there is to go on.
+//
+// Two signals, in order:
+//
+//   1. A record route ends in the record's identifier (`/boards/{id}`,
+//      `/accounts/{account_id}/users/{id}`); a cross-reference ends in the
+//      relationship's name (`/posts/{id}/author`). A terminal parameter is
+//      the stronger signal, and unlike depth alone it survives an entity
+//      nested more deeply than the route that points at it — depth by itself
+//      picked `/posts/{id}/author` over `/accounts/{account_id}/users/{id}`
+//      and then generated that op's required params from the wrong route.
+//   2. Failing that, fewest path segments — the shallower route is the one
+//      the entity is named for, which is what settles a `list` op where
+//      neither route ends in an id (`/boards` over `/members/{id}/boards`).
+//
+// Ties keep the earlier point, so the sorted-key order of the model decides
+// and the output stays byte-stable.
+//
+// The same rule runs at RUNTIME, in each language's makePoint template, when
+// no point's `select.exist` matches. It cannot be shared with them — a
+// template ships standalone, outside this package — so it is written twice on
+// purpose, and both sides must move together.
+function terminalParam(point: any): boolean {
+  const parts: any[] = (point && point.parts) || []
+  const last = 0 < parts.length ? parts[parts.length - 1] : ''
+  return 'string' === typeof last && last.startsWith('{')
+}
+
+
+function ownPoint(points: any[]): any {
+  let best = points[0]
+
+  for (const pt of points) {
+    if (null == pt || null == pt.parts || null == best || null == best.parts) {
+      continue
+    }
+
+    const ptterm = terminalParam(pt)
+    const bestterm = terminalParam(best)
+
+    if (ptterm !== bestterm ? ptterm : pt.parts.length < best.parts.length) {
+      best = pt
+    }
+  }
+
+  return best
+}
+
+
+// Do all these points describe the same route? Then they are alternative
+// selectors on one endpoint (the same path, chosen by different query
+// params), not cross-references to different resources.
+function samePath(points: any[]): boolean {
+  const first = ((points[0] && points[0].parts) || []).join('/')
+
+  return points.every((pt: any) =>
+    first === ((pt && pt.parts) || []).join('/'))
+}
+
+
 function opParams(op: any): any[] {
   let points: any[] = op && op.points ? each(op.points) : []
 
@@ -227,6 +293,25 @@ function opParams(op: any): any[] {
     p.reqd = true === requiredOnAll[p.name]
   })
 
+  // Unrelated cross-references share no param, so the intersection came out
+  // empty and NOTHING is required — which generates a `load({})` that drops
+  // the id. Fall back to the entity's own point and take its params whole.
+  //
+  // Two guards, and both are load-bearing:
+  //
+  //   - only when the intersection produced nothing, so a genuine set of
+  //     alternative routes with a shared param still merges (a `page_id` on
+  //     every route stays required, per-route siblings stay optional);
+  //   - only when the points describe DIFFERENT routes. Points on one path
+  //     that differ solely by optional query params (`/users?email=` and
+  //     `/users?name=`) legitimately require nothing, and are not
+  //     cross-references — collapsing them to one point would drop the
+  //     other's fields from the generated request type, so a caller could
+  //     not express them at all.
+  if (1 < points.length && !out.some((p: any) => p.reqd) && !samePath(points)) {
+    return opParams({ points: [ownPoint(points)] })
+  }
+
   return out
 }