@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/resources/utils/resources-config-operations.urls-builder.utils.js

@@ -11,16 +11,24 @@
  * - Custom collection operations (with resourceOperationLike pointing to collection op):
  *   PUT /api/v1/organizations/{organizationId}/organization-features/reset-features
  *
- * Entity-Level Operations (with entity ID):
- * - READ: GET /api/v1/organizations/{organizationId}/organization-features/{organizationFeaturesId}
- * - UPDATE: PUT /api/v1/organizations/{organizationId}/organization-features/{organizationFeaturesId}
- * - DELETE: DELETE /api/v1/organizations/{organizationId}/organization-features/{organizationFeaturesId}
- * - Custom entity operations (with resourceOperationLike pointing to entity op):
- *   PUT /api/v1/organizations/{organizationId}/organization-features/{organizationFeaturesId}/enable-feature
+ * Entity-Level Operations:
+ * - Regular resources include their entity ID in the route.
+ * - Parent-owned composition singletons and complete M:N paths omit the child /
+ *   junction ID because the declared relationship path uniquely identifies it.
+ * - READ: GET /api/v1/organizations/{organizationId}/organization-features
+ * - UPDATE: PUT /api/v1/organizations/{organizationId}/organization-features
+ * - DELETE: DELETE /api/v1/organizations/{organizationId}/organization-features
+ * - Custom entity operations follow the same entity-id rule as their effective
+ *   core operation: regular entity resources include the id, while
+ *   parent-owned composition singletons and complete M:N paths omit it.
  *
  * Variant Keys (for role-based variants):
  * - LIST admin variant: GET /api/v1/organizations/{organizationId}/organization-features/admin
- * - READ admin variant: GET /api/v1/organizations/{organizationId}/organization-features/{id}/admin
+ * - READ admin variant on regular entity resources:
+ *   GET /api/v1/organizations/{organizationId}/organization-features/{id}/admin
+ * - READ admin variant on parent-owned composition singletons or complete M:N
+ *   paths omits the child/junction ID:
+ *   GET /api/v1/organizations/{organizationId}/organization-features/admin
  * - SEARCH admin variant: GET /api/v1/organizations/{organizationId}/organization-features/search/admin
  *
  * Bulk Operations (collection-level, no entity ID):
@@ -45,12 +53,13 @@
  * - Example: /users/{userId}/organization-members
  * - Combined: /organizations/{orgId}/users/{userId}/organization-member (singular, unique record)
  */
-import { getParentDirectionRelationships, getChildDirectionRelationships, } from '../resources-config.shared.schemas.js';
-import { RelationshipNature, ResourceParentResourceRequirement, ResourceOperationVariantType, ResourceRelationshipAccessScopeStrategy, isOneToOneCardinality } from '../resources.shared.schemas.js';
+import { ResourceGeneratedOperationKind, getParentDirectionRelationships, getChildDirectionRelationships, } from '../resources-config.shared.schemas.js';
+import { RelationshipNature, ResourceParentResourceRequirement, ResourceOperationVariantType, ResourceRelationshipAccessScopeStrategy, ResourceRelationshipCardinality, isOneToOneCardinality, } from '../resources.shared.schemas.js';
 import { ALL_COLLECTION_OPERATIONS, CoreResourceOperation } from '../resources.shared.core.definitions.js';
 import { ResourcesConfigNamingUtils } from './resources-config-naming.utils.js';
 import { Resources_SharedUtils } from '../resources.shared.utils.js';
 import { ResourcesConfig_OperationPathUtils } from './resources-config-operations.path.utils.js';
+import { MAIN_API_BASE_PATH } from '../../requests/manual-controllers-routes-urls.js';
 export class ResourcesConfigOperationsUrlsBuilderUtils {
     static buildUrlsForResourceConfiguration(resourceConfig, allResourceFieldIdentifiers) {
         const results = {};
@@ -82,28 +91,148 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
      * Return the full parent edge set that can legitimately address a resource in URLs.
      *
      * This includes:
-     * - real parent/self relationships from the compiled resource model
+     * - real parent/self relationships from the active operation relationship
+     *   view, falling back to the compiled resource model
      * - synthetic FK-reference parents used to expose alternative nested paths for
      *   non-standard FK fields without polluting the stored relationship graph
      *
      * Frontend navigation and form/runtime consumers should reuse this helper when
      * they need to stay aligned with URL addressability semantics.
+     *
+     * Note that URL parent addressability is intentionally broader than
+     * context-addressed mutation eligibility: self relationships can contribute
+     * navigable tree routes, but singleton mutation target resolution only trusts
+     * compiled `parentRelationships`.
      */
-    static getUrlAddressableParentRelationships(resourceConfig, allResourceFieldIdentifiers) {
-        const realParents = getParentDirectionRelationships(resourceConfig.resourceRelationships);
-        const syntheticFKParents = this.generateSyntheticFKParents(resourceConfig, allResourceFieldIdentifiers);
+    static getUrlAddressableParentRelationships(resourceConfig, allResourceFieldIdentifiers, resourceRelationshipsOverride) {
+        const realParents = getParentDirectionRelationships(resourceRelationshipsOverride ?? resourceConfig.resourceRelationships).filter((relationship) => !this.isInboundFkReferenceParent(relationship, allResourceFieldIdentifiers));
+        // The SAME inbound-FK guard must run over the synthetic parents, not only the real ones.
+        //
+        // {@link isInboundFkReferenceParent} was written to stop a resource being nested under something
+        // that holds an FK pointing AT it — its JSDoc names the symptom exactly: "phantom routes […]
+        // that require an id the target has no notion of and that no controller registers — a guaranteed
+        // 404 for every consumer of the target resource's own routes". But it was applied only to
+        // `realParents`, while {@link generateSyntheticFKParents} appends parents built by REVERSING a
+        // child relationship — which is precisely how an inbound FK reference gets in.
+        //
+        // That gap took the whole `users` API surface off the air on 2026-08-06. Adding
+        // `PLATFORM_ACCESS_GRANTS` with `foreignKeyField: 'operatorUserId'` (non-standard, since USERS'
+        // identifier is `userId`) synthesised a reversed parent, and every users route became
+        // `/operator-user-platform-access-grants/{operatorUserId}/users/{userId}` — the bare
+        // `/users/{userId}` disappeared entirely and the resource 404'd. `applications` was already
+        // broken the same way by `appId` on application-features/metadata/versions (7 phantom
+        // combinations, no bare `/applications`); nobody had noticed because nothing called it.
+        //
+        // Measured over the full core catalogue, this filter changes 4 resources and removes ONLY
+        // phantom shapes — `users` and `applications` regain their base paths, and the two
+        // `referrer-billing-account-referrals/{referrerBillingAccountId}/…-billing-accounts` variants
+        // (addressing a billing account under a billing-account id) go with them. None of the removed
+        // shapes had ever been served: 0 occurrences across the last 8 dev logs.
+        //
+        // WHY THE GENERATOR IS KEPT, and why this filter cannot break its legitimate output.
+        //
+        // `generateSyntheticFKParents` assumes `resourceType1` is the FK HOLDER. Declared that way — the
+        // header example `TODOS → USERS with assignedToUserId` — reversing it yields exactly the intended
+        // `/assigned-to-users/{assignedToUserId}/todos`, and the cardinalities (TODOS MANY → USERS ONE)
+        // make the synthetic's `cardinality2` MANY, so this guard KEEPS it.
+        //
+        // The broken cases declare the FK TARGET first instead (`USERS → PLATFORM_ACCESS_GRANTS`,
+        // `APPLICATIONS → APPLICATION_FEATURES`). The generator cannot tell the difference from
+        // declaration order, but the guard can: it reads FK ownership from CARDINALITY, so a synthetic
+        // built from a target-first declaration comes out `cardinality1 === MANY` and is rejected.
+        //
+        // So the filter separates the two shapes on the only signal that is actually reliable — which is
+        // the same reason `isInboundFkReferenceParent` reads cardinality rather than argument order.
+        //
+        // MEASURED, so the next reader need not guess who this affects: of 335 relationship declarations
+        // repo-wide, the holder-first shape this generator serves has exactly EIGHT production
+        // consumers, all in one app file (`tasks-manager.relationships.ts`) and all the same idea — a
+        // "who created / who is assigned" pointer at USERS or ORGANIZATION_UNITS (`createdByUserId`,
+        // `assignedToUserId`, `postedByUserId`, `organizationUnitId`). The engine declares ZERO; every
+        // one of its 40 core relationships is parent-first.
+        //
+        // That asymmetry IS the failure story. This generator is an APP-AUTHORING feature the engine had
+        // never exercised, so when engine relationships began carrying non-standard FKs
+        // (`operatorUserId`, `appId`) they fell into machinery with no engine-side precedent and nothing
+        // watching it. Keep that in mind before assuming a change here is engine-only.
+        const syntheticFKParents = this.generateSyntheticFKParents(resourceConfig, allResourceFieldIdentifiers, resourceRelationshipsOverride).filter((relationship) => !this.isInboundFkReferenceParent(relationship, allResourceFieldIdentifiers));
         return [...realParents, ...syntheticFKParents];
     }
+    /**
+     * Detect a parent-bucket entry that is actually an INBOUND FK reference —
+     * i.e. the *other* resource holds an FK that points at the current resource,
+     * so the current resource is the FK **target**, not a routable child.
+     *
+     * In the parent bucket the current resource is always `resourceType2`. A
+     * relationship legitimately nests the current resource under `resourceType1`
+     * only when the current resource **holds the foreign key** that references
+     * `resourceType1` (e.g. `draftNotes.userId → users`, `userProfiles.userId →
+     * users`). When the FK lives on `resourceType1` and points back at the
+     * current resource (e.g. `todos.assignedToUserId → users`,
+     * `tasks.assignedToUserId → users`), nesting the current resource under
+     * `resourceType1` is semantically inverted: it yields phantom routes like
+     * `/assigned-to-user-todos/{assignedToUserId}/users/search` that require an
+     * id the target has no notion of and that no controller registers — a
+     * guaranteed 404 for every consumer of the target resource's own routes.
+     *
+     * The correct holder-under-target route (`/assigned-to-users/{userId}/todos`)
+     * is produced independently by {@link generateSyntheticFKParents} from the
+     * FK-holder's child bucket, so excluding the inbound direction here loses no
+     * legitimate addressability.
+     *
+     * FK ownership is read off the relationship shape (no schema access needed):
+     * - `cardinality2 === MANY` → the current resource is the many side and holds
+     *   the FK → genuine child, keep.
+     * - `cardinality1 === MANY` (so the current `one` side is referenced by a
+     *   many holder) → current is the FK target → inbound, drop.
+     * - `1:1` → the current resource holds the FK only when the FK is
+     *   `resourceType1`'s standard identifier (a standard parent reference like
+     *   `userProfiles.userId`); a non-standard FK (`assignedToUserId`) on a 1:1
+     *   edge belongs to `resourceType1` and points back at current → inbound,
+     *   drop.
+     *
+     * Only `REFERENCE`-nature edges can be inbound; compositions/associations
+     * always contain the current resource as a genuine child, and self
+     * relationships (`resourceType1 === resourceType2`) are legitimate tree
+     * routes — both are never treated as inbound.
+     */
+    static isInboundFkReferenceParent(relationship, allResourceFieldIdentifiers) {
+        if (relationship.resourceType1 === relationship.resourceType2) {
+            return false;
+        }
+        if (relationship.nature !== RelationshipNature.REFERENCE) {
+            return false;
+        }
+        const currentHoldsForeignKey = relationship.cardinality2 === ResourceRelationshipCardinality.MANY
+            ? true
+            : relationship.cardinality1 === ResourceRelationshipCardinality.MANY
+                ? false
+                : relationship.foreignKeyField != null
+                    && relationship.foreignKeyField === allResourceFieldIdentifiers[relationship.resourceType1];
+        return !currentHoldsForeignKey;
+    }
     /**
      * Build URLs for a specific operation
      */
     static buildUrlsForOperation(operation, resourceConfig, allResourceFieldIdentifiers) {
         const initiatorInfos = [];
-        const allParentsForURLs = this.getUrlAddressableParentRelationships(resourceConfig, allResourceFieldIdentifiers);
+        const coreOperation = this.getCoreOperation(operation);
+        // Scope-required reference search: an edge tagged with `urlOperationScope`
+        // contributes its URL ONLY for the listed core operations (the scope-anchored
+        // peer-under-scope edge restricts to SEARCH/LIST). Untagged edges (every
+        // normal relationship) are unaffected.
+        const allParentsForURLs = this.getUrlAddressableParentRelationships(resourceConfig, allResourceFieldIdentifiers, operation.resourceRelationships).filter((rel) => !rel.urlOperationScope || rel.urlOperationScope.includes(coreOperation));
         // Generate URL paths from all parent combinations
         const parentInfos = this.getParentResourceInfos(allParentsForURLs, allResourceFieldIdentifiers);
-        const parentCombinations = this.generateParentCombinations(parentInfos);
-        const coreOperation = this.getCoreOperation(operation);
+        const parentCombinations = this.generateParentCombinations(parentInfos).filter((parentCombo) => coreOperation !== CoreResourceOperation.LIST
+            || !this.isCompleteManyToManyPath(parentCombo));
+        // A complete M:N parent path identifies one junction row: for example,
+        // organization + user identifies THE organization-membership. That path is
+        // therefore an entity address owned by READ. LIST remains available under
+        // either individual parent (members by organization, memberships by user),
+        // but must not also claim the complete path with the same GET method. Doing
+        // so registers two different operation contracts on one HTTP route and
+        // makes router ordering decide which contract is actually served.
         for (const parentCombo of parentCombinations) {
             const urlInfo = this.buildUrlForParentCombination(parentCombo, resourceConfig, operation, allResourceFieldIdentifiers, false);
             const initiatorInfo = {
@@ -124,10 +253,38 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
                 if (userSelfParentIndex >= 0) {
                     const anonymousCombo = parentCombo.map((p, i) => {
                         if (i === userSelfParentIndex) {
+                            // Synthesize the ANONYMOUS_USERS parent that masks the USER_SELF
+                            // primary parent for the anonymous URL variant.
+                            //
+                            // `foreignKeyField` MUST become the anonymous user's own FK
+                            // (`anonymousUserId`), NOT the inherited `userId` from the
+                            // authenticated parent. `buildUrlForParentCombination` derives
+                            // BOTH the route param name (`foreignKeyField || fieldIdentifier`)
+                            // AND the param's `relationshipField` (the child-filter FK) from
+                            // `foreignKeyField`. Leaving it as `userId` was the W7.3a bug:
+                            //  - the route param bound `req.params.userId`, which
+                            //    `extractInitiatorIds` maps to `initiatorIds.userId` → the
+                            //    ANONYMOUS_SESSION ExecutionContext constructor rejects any
+                            //    authenticated identity field → 500 at
+                            //    `handleAnonymousSessionInit`; and
+                            //  - the nested-LIST child filter keyed on `userId` (null for
+                            //    anonymous rows), never on the `anonymousUserId` column that
+                            //    actually stores the session handle.
+                            // With `anonymousUserId`, the param is ignored by
+                            // `extractInitiatorIds` (the session id is set from the
+                            // `x-anonymous-session-init` header), the coherence check pins the
+                            // URL uuid to the session uuid (defense in depth), and the child
+                            // filter targets the correct column.
+                            //
+                            // The URL segment stays honest: `anonymousUserId` IS the standard
+                            // identifier of `anonymous_users`, so `extractRelationshipPrefix`
+                            // strips it → no redundant prefix → `/anonymous-users/…`, parallel
+                            // to the authenticated `/users/{userId}/…` route.
                             return {
                                 ...p,
                                 resourceType: 'anonymous_users',
                                 fieldIdentifier: 'anonymousUserId',
+                                foreignKeyField: 'anonymousUserId',
                             };
                         }
                         return p;
@@ -152,6 +309,8 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
                 isBulk: operation.isBulkOperation,
                 isCount: coreOperation === CoreResourceOperation.COUNT,
                 isSearch: coreOperation === CoreResourceOperation.SEARCH,
+                // Informational only: initiatorInfos.parameters remain the canonical
+                // source for FK/relationship-field route evidence.
                 parentCombinations: parentCombinations.map(combo => combo.map(parent => parent.resourceType))
             }
         };
@@ -159,7 +318,10 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
     static buildOperationFrontendRoutePaths(resourceConfig, operation, allResourceFieldIdentifiers) {
         if (!this.isUrlisable(operation.variantType))
             return []; // other presets are not routable
-        const allParentsForURLs = this.getUrlAddressableParentRelationships(resourceConfig, allResourceFieldIdentifiers);
+        // Mirror buildUrlsForOperation's `urlOperationScope` filter so frontend route
+        // generation and backend route registration stay in lock-step.
+        const coreOperation = this.getCoreOperation(operation);
+        const allParentsForURLs = this.getUrlAddressableParentRelationships(resourceConfig, allResourceFieldIdentifiers, operation.resourceRelationships).filter((rel) => !rel.urlOperationScope || rel.urlOperationScope.includes(coreOperation));
         const parentInfos = this.getParentResourceInfos(allParentsForURLs, allResourceFieldIdentifiers);
         const parentCombinations = this.generateParentCombinations(parentInfos);
         const frontendRoutePaths = [];
@@ -197,11 +359,44 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
                 resourceType: params.targetResourceType,
             });
         }
+        const fileRouteSegment = ResourcesConfigNamingUtils.toKebabCase(params.fieldName.replace(/\./g, '-'));
         return {
-            url: `${url}/files/${params.fieldName}`,
+            url: `${url}/files/${fileRouteSegment}`,
             parameters,
         };
     }
+    /**
+     * Build the resource-integrated file **serve** (GET) route for an operation.
+     *
+     * Symmetric to `buildFileUploadRouteForOperation`, but always entity-addressed and
+     * terminated by the specific `fileId`:
+     * `{operationRoute}/{resourceId}/files/{fieldSegment}/{fileId}`.
+     *
+     * The serve route inherits authorization from the parent resource's READ
+     * operation (the `{resourceId}` identifies the record whose access is checked),
+     * so the URL is single-sourced here for BOTH the backend Express route
+     * registration and the frontend fetch URL. The trailing `fileId` is a plain path
+     * param resolved in the serve handler (NOT a resource-identifying parameter), so
+     * it is intentionally not added to `parameters` — those stay the resource/parent
+     * identifiers the execution context needs. Reuses the upload builder to append
+     * the entity id + `/files/<field>`.
+     */
+    static buildFileServeRouteForOperation(params) {
+        const base = this.buildFileUploadRouteForOperation({
+            operationRouteUrl: params.operationRouteUrl,
+            operationParameters: params.operationParameters,
+            targetResourceType: params.targetResourceType,
+            targetResourceFieldIdentifier: params.targetResourceFieldIdentifier,
+            fieldName: params.fieldName,
+            requiresTargetResourceId: true,
+            isFrontend: params.isFrontend,
+        });
+        const fileIdPlaceholder = params.isFrontend ? ':fileId' : '{fileId}';
+        return {
+            url: `${base.url}/${fileIdPlaceholder}`,
+            parameters: base.parameters,
+        };
+    }
     // ===========================================================================================
     // PARENT RELATIONSHIP MANAGEMENT
     // =========================================================================================
@@ -214,7 +409,7 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
    * - NOT /users/{userId}/assigned-to-todos (prefix on child)
    */
     static buildUrlForParentCombination(parentCombo, resourceConfig, operation, allResourceFieldIdentifiers, isFrontend = false) {
-        const segments = !isFrontend ? ['/api/v1'] : [];
+        const segments = !isFrontend ? [MAIN_API_BASE_PATH] : [];
         const parameters = [];
         // For frontend routes (React Router), use :paramName format
         // For backend routes (Express), use {paramName} format
@@ -240,6 +435,7 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
                 fieldIdentifier: parameterName,
                 resourceType: parent.resourceType,
                 relationshipField: parent.foreignKeyField,
+                scopeViaJunction: parent.scopeViaJunction,
             });
         }
         // Add main resource segment (no longer modified by relationship context - prefix is on parent)
@@ -261,8 +457,34 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
     static getParentResourceInfos(parentRelationships, allResourceFieldIdentifiers) {
         const parentInfos = [];
         for (const relationship of parentRelationships) {
+            const compiledRelationship = Resources_SharedUtils.ensureCompiledRelationship(relationship, allResourceFieldIdentifiers);
             const resourceType = relationship.resourceType1;
-            const fieldIdentifier = allResourceFieldIdentifiers[resourceType];
+            const fieldIdentifier = allResourceFieldIdentifiers[resourceType] ?? relationship.foreignKeyField;
+            if (!fieldIdentifier) {
+                /*
+                 * A STANDALONE parent is NEVER part of a URL, so it cannot need a name in one.
+                 *
+                 * `generateParentCombinations` filters STANDALONE parents out before any segment is built,
+                 * and the only consumer of `fieldIdentifier` is the parameter name at that point — so
+                 * demanding one here refuses a configuration over data the URL provably discards. Skipping
+                 * changes nothing downstream: such a parent is dropped a few steps later regardless.
+                 *
+                 * What it fixes is severe and silent. `initializeResources` DELETES an excluded type's field
+                 * identifier, so a surviving resource anchored to an excluded parent threw here — and
+                 * `generateUrlsForApiCallOperations` CATCHES that and `console.error`s it, leaving the
+                 * registry "built successfully" with every operation carrying no url. Measured on the
+                 * application-creation workbench, whose resources anchor to APPLICATION through exactly this
+                 * STANDALONE shape: excluding every core type gave 1 resource, 1 logged error and
+                 * `listUrl: undefined`, while every unit test that stubbed the transport passed.
+                 *
+                 * A NON-standalone parent still throws: that URL genuinely needs the parent's name, so an
+                 * unresolvable one is a real configuration defect rather than a discarded input.
+                 */
+                if (relationship.accessScopeStrategy === ResourceRelationshipAccessScopeStrategy.STANDALONE) {
+                    continue;
+                }
+                throw new Error(`Cannot generate URL parent info for "${resourceType}" without a registered field identifier or relationship foreignKeyField.`);
+            }
             parentInfos.push({
                 resourceType,
                 fieldIdentifier,
@@ -270,12 +492,50 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
                 isOptional: relationship.parentResourceRequirement === ResourceParentResourceRequirement.OPTIONAL,
                 accessScopeStrategy: relationship.accessScopeStrategy,
                 foreignKeyField: relationship.foreignKeyField,
+                childForeignKeyField: compiledRelationship.resolvedSemantics.persistence.foreignKey?.fieldIdentifier,
+                relationshipNature: relationship.nature,
+                jointResourceType: relationship.jointResourceType,
+                scopeViaJunction: relationship.scopeViaJunction,
+                cardinality1: relationship.cardinality1,
                 cardinality2: relationship.cardinality2,
                 order: 0 // Will be calculated later
             });
         }
+        // Collapse multiple parents that resolve to the SAME resourceType down to a
+        // single URL parent, preferring the ROUTABLE one. A resource can carry both
+        // a STANDALONE primary anchor (which declares `resourcePrimaryScope` but is
+        // intentionally inert for URL routing — see the primary-scope derivation in
+        // the config factory) AND a routable peer of the same type (e.g. an M:N
+        // junction's OPTIONAL_CONTEXT side). Without this collapse,
+        // `orderParentResourceInfos`' per-resourceType dedup keeps whichever sorts
+        // first — the STANDALONE anchor (primary sorts first) — and then
+        // `generateParentCombinations` drops it as STANDALONE, so the route is lost
+        // entirely. That is the exact bug that left ORGANIZATION_MEMBERS unreachable
+        // under `/organizations/{organizationId}/organization-members` while it still
+        // routed under `/users/{userId}/...`. We keep the routable peer's OWN flags
+        // (notably its non-primary, OPTIONAL_CONTEXT scope) so the route stays
+        // optional — preserving BOTH the org-side and user-side URLs of the junction.
+        const collapsedByResourceType = new Map();
+        for (const info of parentInfos) {
+            const existing = collapsedByResourceType.get(info.resourceType);
+            if (!existing || this.isMoreUrlRoutableParent(info, existing)) {
+                collapsedByResourceType.set(info.resourceType, info);
+            }
+        }
         // Order by dependency chain, then alphabetically
-        return this.orderParentResourceInfos(parentInfos, parentRelationships);
+        return this.orderParentResourceInfos([...collapsedByResourceType.values()], parentRelationships);
+    }
+    /**
+     * Rank a candidate URL parent against the one currently kept for the same
+     * resourceType. A routable (non-STANDALONE) parent always beats a STANDALONE
+     * anchor — a STANDALONE relationship is by definition off the URL surface, so
+     * it must never shadow a peer that DOES route. Two equally-routable (or two
+     * equally-STANDALONE) parents keep the first encountered (stable).
+     */
+    static isMoreUrlRoutableParent(candidate, existing) {
+        const candidateRoutable = candidate.accessScopeStrategy !== ResourceRelationshipAccessScopeStrategy.STANDALONE;
+        const existingRoutable = existing.accessScopeStrategy !== ResourceRelationshipAccessScopeStrategy.STANDALONE;
+        return candidateRoutable && !existingRoutable;
     }
     /**
      * Order parent resources by dependency chain and alphabetically
@@ -342,11 +602,20 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
     static generateParentCombinations(parentInfos) {
         // Filter out STANDALONE relationships - they are NEVER included in URL paths
         const urlParents = parentInfos.filter(p => p.accessScopeStrategy !== ResourceRelationshipAccessScopeStrategy.STANDALONE);
-        const primaryScope = urlParents.filter(p => p.isPrimaryScope);
-        const mandatoryContext = urlParents.filter(p => !p.isPrimaryScope &&
+        // Scope-anchored peer-under-scope edges (scope-required reference search) are
+        // ADDITIVE access paths: each adds a single-parent scoped route (e.g.
+        // /organizations/{org}/users/search) WITHOUT altering the target's normal
+        // addressability — in particular it must NOT suppress the target's bare/global
+        // route (the empty combination is skipped below whenever any parent exists, so
+        // a scope-anchored edge folded into the normal powerset would silently drop
+        // /users/search). Handle them separately, appended as their own routes.
+        const scopeAnchoredParents = urlParents.filter(p => p.scopeViaJunction);
+        const standardParents = urlParents.filter(p => !p.scopeViaJunction);
+        const primaryScope = standardParents.filter(p => p.isPrimaryScope);
+        const mandatoryContext = standardParents.filter(p => !p.isPrimaryScope &&
             p.accessScopeStrategy === ResourceRelationshipAccessScopeStrategy.REQUIRES_CONTEXT);
         // OPTIONAL_CONTEXT generates optional URL paths (with and without parent)
-        const optionalContext = urlParents.filter(p => p.accessScopeStrategy === ResourceRelationshipAccessScopeStrategy.OPTIONAL_CONTEXT &&
+        const optionalContext = standardParents.filter(p => p.accessScopeStrategy === ResourceRelationshipAccessScopeStrategy.OPTIONAL_CONTEXT &&
             !p.isPrimaryScope);
         // Generate all combinations of optional context parents
         const optionalCombinations = this.generateOptionalCombinations(optionalContext);
@@ -357,10 +626,15 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
                 allCombinations.push(combination);
             }
         }
-        // If no combinations, at least return empty combination
+        // If no standard combinations, at least return the empty (bare) combination.
         if (allCombinations.length === 0) {
             allCombinations.push([]);
         }
+        // Append each scope-anchored edge as its OWN single-parent route, on top of
+        // the normal addressability above (additive — never suppresses the bare).
+        for (const scopeAnchoredParent of scopeAnchoredParents) {
+            allCombinations.push([scopeAnchoredParent]);
+        }
         return allCombinations;
     }
     /**
@@ -384,8 +658,12 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
      * - SEARCH: /search suffix (single occurrence)
      * - COUNT: /count suffix (single occurrence)
      * - Custom collection operations: Add operation name (e.g., /reset-features)
-     * - Core entity operations (READ, UPDATE, DELETE): No suffix after entity ID
-     * - Custom entity operations: Add operation name after entity ID (e.g., /{id}/rotate)
+     * - Core entity operations (READ, UPDATE, DELETE): No suffix after the entity
+     *   target. Regular resources include an entity ID; relationship-unique
+     *   singleton and complete M:N paths omit it.
+     * - Custom entity operations: Add the operation name after the entity target
+     *   (e.g., /{id}/rotate on regular resources, or /rotate on id-less
+     *   singleton / complete M:N paths).
      */
     static getOperationSegments(operation, resourceConfig, allResourceFieldIdentifiers, parentCombo, isFrontend = false) {
         const segments = [];
@@ -395,23 +673,42 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
         // For frontend routes (React Router), use :paramName format
         // For backend routes (Express), use {paramName} format
         const formatParam = (paramName) => isFrontend ? `:${paramName}` : `{${paramName}}`;
+        const generatedRegenerate = operation.generatedOperation?.kind === ResourceGeneratedOperationKind.GENERATED_FILE_REGENERATE
+            ? operation.generatedOperation
+            : undefined;
+        const generatedCollectionExport = operation.generatedOperation?.kind === ResourceGeneratedOperationKind.GENERATED_COLLECTION_EXPORT;
         // Determine if this is a custom operation (not a core operation)
         const isCustomOperation = !Object.values(CoreResourceOperation).includes(operationName);
         if (isCollectionLevelOperation) {
             // For custom collection operations, add the operation name segment
             if (isCustomOperation) {
-                const operationSegment = ResourcesConfigNamingUtils.toKebabCase(operationName);
-                segments.push(operationSegment);
+                // The export companion is the one custom collection operation that must NOT be named here.
+                // Its identifier (`collectionExport:list`) would kebab-case into a segment, and it needs the
+                // `search` segment its SOURCE gets — which is appended further down, from
+                // `resourceOperationLike`. So the literal `export` segment is pushed AFTER that, and this
+                // branch contributes nothing.
+                if (!generatedCollectionExport) {
+                    const operationSegment = ResourcesConfigNamingUtils.toKebabCase(operationName);
+                    segments.push(operationSegment);
+                }
+            }
+            // Core collection operations (LIST, CREATE, etc.) don't add an operation
+            // name on the BACKEND — they differentiate by HTTP method (GET for LIST,
+            // POST for CREATE). FRONTEND routes carry no HTTP method, so an addressable
+            // core CREATE must carry an explicit `create` segment or it resolves to the
+            // bare collection path and collides with LIST — shadowing the listing on a
+            // cold load / refresh. Mirrors the `search`/`count` disambiguation below.
+            // (LIST stays at the bare collection path; SEARCH/COUNT/CREATE disambiguate.)
+            else if (isFrontend && this.getCoreOperation(operation) === CoreResourceOperation.CREATE) {
+                segments.push('create');
             }
-            // Core collection operations (LIST, CREATE, etc.) don't add operation name
-            // They differentiate by HTTP method (GET for LIST, POST for CREATE, etc.)
         }
         else {
             // Entity-level operations
             // Skip resource ID when the parent combination uniquely identifies the resource:
             // - One-to-one: only one instance per parent (e.g., organization-preference)
             // - Complete many-to-many: both foreign keys specified (e.g., org + user = unique membership)
-            if (!this.isOneToOneRelationship(parentCombo) && !this.isCompleteManyToManyPath(parentCombo)) {
+            if (generatedRegenerate || (!this.isOneToOneRelationship(parentCombo) && !this.isCompleteManyToManyPath(parentCombo))) {
                 const resourceParam = allResourceFieldIdentifiers[resourceConfig.resourceIdentifier];
                 segments.push(formatParam(resourceParam));
                 parameterInfos.push({
@@ -419,10 +716,15 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
                     resourceType: resourceConfig.resourceIdentifier
                 });
             }
-            // For custom entity operations, add the operation name after the entity ID
+            // For custom entity operations, add the operation name after the entity target.
             if (isCustomOperation) {
-                const operationSegment = ResourcesConfigNamingUtils.toKebabCase(operationName);
-                segments.push(operationSegment);
+                if (generatedRegenerate) {
+                    segments.push('files', ResourcesConfigNamingUtils.toKebabCase(generatedRegenerate.fieldName.replace(/\./g, '-')), 'regenerate');
+                }
+                else {
+                    const operationSegment = ResourcesConfigNamingUtils.toKebabCase(operationName);
+                    segments.push(operationSegment);
+                }
             }
         }
         // Add bulk suffix if needed
@@ -438,6 +740,15 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
         if (coreOperation === CoreResourceOperation.COUNT) {
             segments.push('count');
         }
+        // The export companion sits one segment BELOW the listing it exports, so it inherits that
+        // listing's whole path — every parent combination, and the `search` disambiguator above:
+        //   LIST   → /organizations/{org}/todos/export
+        //   SEARCH → /organizations/{org}/todos/search/export
+        // A resource exporting both verbs therefore gets two distinct routes without a naming scheme,
+        // and neither can shadow the listing itself (a literal segment, appended last).
+        if (generatedCollectionExport) {
+            segments.push('export');
+        }
         // Add variant key if exists
         if (operation.variantKey) {
             segments.push(operation.variantKey);
@@ -480,20 +791,29 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
         // If parent resource type is provided, remove it from the end of base name
         // e.g., "assignedToUser" with parent "users" → "assignedTo"
         if (parentResourceType) {
-            // Get singular form of parent resource type (e.g., "users" → "user")
+            // Get singular form of parent resource type (e.g., "users" → "user").
             const parentSingular = ResourcesConfigNamingUtils.singularize(parentResourceType);
-            // Capitalize first letter to match camelCase pattern (e.g., "user" → "User")
-            const parentSingularCapitalized = parentSingular.charAt(0).toUpperCase() + parentSingular.slice(1);
-            // Remove parent resource type from the end if present
-            // Check both capitalized form (e.g., "assignedToUser" ends with "User")
-            // and exact match (e.g., "user" ends with "User" when lowercased)
-            if (baseName.endsWith(parentSingularCapitalized)) {
-                baseName = baseName.slice(0, -parentSingularCapitalized.length);
-            }
-            else if (baseName.toLowerCase() === parentSingular.toLowerCase()) {
-                // Exact match for standard FK (e.g., "user" matches parent "users")
+            // Compare using WORD-BOUNDARY-SAFE camelCase forms so that multi-word
+            // snake_case resource types work identically to single-word ones. The FK
+            // base name is always camelCase (e.g. "anonymousUserId" → "anonymousUser"),
+            // while a snake_case parent singular is "anonymous_user"; comparing the raw
+            // forms ("Anonymous_user" / "anonymous_user") misses the strip and emits a
+            // redundant prefix ("anonymous-user-anonymous-users"). PascalCase folds both
+            // to "AnonymousUser" so `endsWith` matches on the word boundary, and a
+            // separator-stripped lowercase compare catches the exact standard-FK case.
+            const parentSingularPascal = ResourcesConfigNamingUtils.toPascalCase(parentSingular);
+            const stripSeparators = (value) => value.replace(/[_\-\s]/g, '').toLowerCase();
+            if (stripSeparators(baseName) === stripSeparators(parentSingular)) {
+                // Exact match for a standard FK: the base name IS the parent's own
+                // identifier (e.g. "userId"→"users", "anonymousUserId"→"anonymous_users")
+                // → no prefix needed.
                 baseName = '';
             }
+            else if (baseName.endsWith(parentSingularPascal)) {
+                // Non-standard FK carrying the parent type as a trailing word
+                // (e.g. "assignedToUser"/"approvedByManager" end with "User"/"Manager").
+                baseName = baseName.slice(0, -parentSingularPascal.length);
+            }
         }
         // If baseName is empty after stripping, return empty (no prefix needed)
         if (!baseName)
@@ -546,13 +866,13 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
      * Used to determine if resource should use singular naming and no entity ID
      */
     static isOneToOneRelationship(parentCombo) {
-        // Check for one-to-one relationships in any of these scenarios:
-        // 1. Exactly one primary scope parent with ONE cardinality
-        // 2. Exactly one parent (any scope) with ONE cardinality
         if (parentCombo.length === 1) {
             const parent = parentCombo[0];
-            // Check if the cardinality from parent to child is 1:1 (ONE or ZERO_OR_ONE)
-            return isOneToOneCardinality(parent.cardinality2);
+            return parent.relationshipNature === RelationshipNature.COMPOSITION
+                && parent.cardinality1 === ResourceRelationshipCardinality.ONE
+                && isOneToOneCardinality(parent.cardinality2)
+                && parent.accessScopeStrategy !== ResourceRelationshipAccessScopeStrategy.STANDALONE
+                && Boolean(parent.childForeignKeyField);
         }
         return false;
     }
@@ -564,33 +884,26 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
      * Example: /organizations/{orgId}/users/{userId}/organization-member
      * This uniquely identifies THE membership between this org and user
      *
-     * Important: This should NOT match hierarchical relationships with optional parents.
-     * For example, todos with optional todoList parent is NOT a junction table.
-     * Junction tables require BOTH parents to be required (REQUIRES_CONTEXT or isPrimaryScope).
+     * Important: This should NOT match hierarchical relationships with optional
+     * parents. Factory-generated junction parents are OPTIONAL_CONTEXT so each
+     * side can also expose an independent URL, but the complete path is proven by
+     * the association semantics plus shared jointResourceType, not by requiredness.
      */
     static isCompleteManyToManyPath(parentCombo) {
-        // For a complete many-to-many path, we need:
-        // 1. Exactly 2 parents 
-        // 2. One with primary scope (e.g., organization)
-        // 3. One without primary scope (e.g., user)
-        // 4. BOTH parents must be required (not OPTIONAL_CONTEXT)
-        //    - Primary scope parents are always required
-        //    - Non-primary scope parents must have REQUIRES_CONTEXT
+        // For a complete many-to-many path, we need exactly two association parents
+        // that both point at the same junction resource. Do not require
+        // REQUIRES_CONTEXT here: factory-real M:N junction parents are intentionally
+        // OPTIONAL_CONTEXT so each side can generate independent URLs as well.
         if (parentCombo.length === 2) {
-            const primaryScopeParents = parentCombo.filter(parent => parent.isPrimaryScope);
-            const nonPrimaryScopeParents = parentCombo.filter(parent => !parent.isPrimaryScope);
-            // Must have exactly one primary and one non-primary scope parent
-            if (primaryScopeParents.length !== 1 || nonPrimaryScopeParents.length !== 1) {
-                return false;
-            }
-            // For a true junction table, BOTH parents must be required in the URL path:
-            // - Primary scope is always required
-            // - Non-primary scope must have REQUIRES_CONTEXT (not OPTIONAL_CONTEXT)
-            // If the non-primary parent has OPTIONAL_CONTEXT, this is a hierarchical relationship,
-            // not a junction table (e.g., todos with optional todoList parent)
-            const nonPrimaryParent = nonPrimaryScopeParents[0];
-            const isNonPrimaryRequired = nonPrimaryParent.accessScopeStrategy === ResourceRelationshipAccessScopeStrategy.REQUIRES_CONTEXT;
-            return isNonPrimaryRequired;
+            const jointResourceTypes = parentCombo
+                .map((parent) => parent.jointResourceType)
+                .filter((jointResourceType) => Boolean(jointResourceType));
+            return jointResourceTypes.length === 2
+                && new Set(jointResourceTypes).size === 1
+                && new Set(parentCombo.map((parent) => parent.foreignKeyField || parent.fieldIdentifier)).size === parentCombo.length
+                && parentCombo.every((parent) => parent.relationshipNature === RelationshipNature.ASSOCIATION
+                    && parent.cardinality1 === ResourceRelationshipCardinality.ONE
+                    && parent.cardinality2 === ResourceRelationshipCardinality.MANY);
         }
         return false;
     }
@@ -608,9 +921,9 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
      *
      * Edge Cases Handled:
      * - M:N relationships: Excluded (not in childRelationships)
-     * - Self-referencing: Filtered out (line 781)
-     * - Missing standard FK: Skipped gracefully (line 785-787)
-     * - Standard FK (e.g., USER_SELF with userId): Correctly identified and skipped (line 793-795)
+     * - Self-referencing: Filtered out before synthetic parent creation
+     * - Missing standard FK: Skipped gracefully when the parent resource is unknown
+     * - Standard FK (e.g., USER_SELF with userId): Correctly identified and skipped
      *
      * Known Minor Inefficiency:
      * - Multiple non-standard FKs to same resource type (e.g., assignedToUserId + createdByUserId)
@@ -621,10 +934,10 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
      * @param allResourceFieldIdentifiers - Map of resourceType → standard field identifier
      * @returns Array of synthetic parent relationships (for URL generation ONLY)
      */
-    static generateSyntheticFKParents(resourceConfig, allResourceFieldIdentifiers) {
+    static generateSyntheticFKParents(resourceConfig, allResourceFieldIdentifiers, resourceRelationshipsOverride) {
         const syntheticParents = [];
         const resourceIdentifier = resourceConfig.resourceIdentifier;
-        const childRelationships = getChildDirectionRelationships(resourceConfig.resourceRelationships);
+        const childRelationships = getChildDirectionRelationships(resourceRelationshipsOverride ?? resourceConfig.resourceRelationships);
         // Scan child relationships (where current resource is resourceType1/parent)
         for (const rel of childRelationships) {
             // Only process relationships with explicit FK field
@@ -690,4 +1003,4 @@ export class ResourcesConfigOperationsUrlsBuilderUtils {
         return syntheticParents;
     }
 }
-//# sourceMappingURL=resources-config-operations.urls-builder.utils.js.map
+//# sourceMappingURL=resources-config-operations.urls-builder.utils.js.map